drupal-ddev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DDEV for Drupal Development

面向Drupal开发的DDEV使用指南

Comprehensive patterns for using DDEV as your local Drupal development environment, including setup, configuration, workflow optimization, and troubleshooting.

本文提供了将DDEV用作本地Drupal开发环境的全面实践方案，包括环境搭建、配置、工作流优化及故障排查等内容。

When This Skill Activates

本技能适用场景

Activates when working with DDEV local development including:

DDEV configuration (.ddev/config.yaml)
Local environment setup and management
Database import/export operations
Drush integration
Xdebug and debugging tools
Performance optimization
Multi-site and custom commands

当您进行以下DDEV本地开发相关操作时，本技能将为您提供支持：

DDEV配置(.ddev/config.yaml)
本地环境搭建与管理
数据库导入/导出操作
Drush集成
Xdebug及调试工具使用
性能优化
多站点配置与自定义命令

Available Topics

可用主题

Core Setup

核心搭建

@references/installation.md - Installing and configuring DDEV
@references/config-yaml.md - .ddev/config.yaml reference
@references/commands.md - Essential DDEV commands

@references/installation.md - DDEV的安装与配置
@references/config-yaml.md - .ddev/config.yaml参考文档
@references/commands.md - 必备DDEV命令

Database Operations

数据库操作

@references/database.md - Import, export, and snapshot workflows
@references/drush.md - Using Drush with DDEV

@references/database.md - 导入、导出及快照工作流
@references/drush.md - 在DDEV中使用Drush

Development Tools

开发工具

@references/xdebug.md - Debugging with Xdebug
@references/mailhog.md - Email testing with MailHog
@references/solr.md - Local Solr search setup

@references/xdebug.md - 使用Xdebug进行调试
@references/mailhog.md - 使用MailHog进行邮件测试
@references/solr.md - 本地Solr搜索环境搭建

Advanced

进阶内容

@references/custom-commands.md - Creating project-specific commands
@references/hooks.md - Pre/post hooks automation
@references/performance.md - Optimizing DDEV performance
@references/multisite.md - Multi-site configuration

See

/references/

directory for complete documentation.

@references/custom-commands.md - 创建项目专属命令
@references/hooks.md - 前置/后置钩子自动化
@references/performance.md - DDEV性能优化
@references/multisite.md - 多站点配置

完整文档请查看

/references/

目录。

Quick Reference

速查参考

Essential Commands

必备命令

bash

undefined

bash

undefined

Start project

启动项目

ddev start

Stop project

停止项目

ddev stop

Restart services

重启服务

ddev restart

SSH into web container

进入Web容器

ddev ssh

Run Drush commands

执行Drush命令

ddev drush cr ddev drush status ddev drush config:status

Run Composer

执行Composer命令

ddev composer require drupal/module_name ddev composer update

Database operations

数据库操作

ddev import-db --file=backup.sql.gz ddev export-db --file=backup.sql.gz ddev snapshot

View logs

查看日志

ddev logs ddev logs -f # Follow mode

ddev logs ddev logs -f # 实时跟踪模式

Describe project

查看项目信息

ddev describe

Access URLs

访问站点

ddev launch # Open site in browser

undefined

ddev launch # 在浏览器中打开站点

undefined

Basic .ddev/config.yaml

基础.ddev/config.yaml配置

yaml

name: myproject
type: drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.6"
nodejs_version: "20"

yaml

name: myproject
type: drupal10
docroot: web
php_version: "8.3"
webserver_type: nginx-fpm
database:
  type: mariadb
  version: "10.6"
nodejs_version: "20"

Additional services

额外服务

additional_services:

solr

additional_services:

solr

Custom upload/execution limits

自定义上传/执行限制

upload_dirs:

web/sites/default/files

upload_dirs:

web/sites/default/files

Performance settings

性能设置

performance_mode: mutagen # For macOS

---

performance_mode: mutagen # 适用于macOS

---

Common Workflows

常见工作流

New Drupal Project

新建Drupal项目

bash

undefined

bash

undefined

Create project directory

创建项目目录

mkdir myproject && cd myproject

Initialize DDEV

初始化DDEV

ddev config --project-type=drupal10 --docroot=web --php-version=8.3

Install Drupal via Composer

通过Composer安装Drupal

ddev composer create drupal/recommended-project

Install Drush

安装Drush

ddev composer require drush/drush

Start DDEV

启动DDEV

ddev start

Install Drupal

安装Drupal

ddev drush site:install standard --site-name="My Site" --account-name=admin

Launch site

打开站点

ddev launch

undefined

ddev launch

undefined

Import Existing Project

导入现有项目

bash

undefined

bash

undefined

Clone repository

克隆代码仓库

git clone repo-url myproject && cd myproject

Start DDEV (reads .ddev/config.yaml)

启动DDEV（读取.ddev/config.yaml配置）

ddev start

Install dependencies

安装依赖

ddev composer install

Import database

导入数据库

ddev import-db --file=path/to/backup.sql.gz

Import files (if needed)

导入文件（如有需要）

ddev import-files --source=/path/to/files

Run updates

执行更新

ddev drush updb -y ddev drush cr

Launch

打开站点

ddev launch

undefined

ddev launch

undefined

Database Sync from Remote

从远程服务器同步数据库

bash

undefined

bash

undefined

Option 1: Download backup and import

方式1：下载备份文件后导入

Use your hosting provider's CLI or dashboard to create/download a DB backup

使用主机提供商的CLI或控制台创建/下载数据库备份

Example with a generic provider:

通用提供商示例：

scp user@remote.server:/path/to/backup.sql.gz backup.sql.gz

Import to local

导入到本地环境

ddev import-db --file=backup.sql.gz

Option 2: Using DDEV pull (if configured with a provider integration)

方式2：使用DDEV pull（已配置提供商集成时）

ddev pull --environment=live

Run updates after import

导入后执行更新

ddev drush updb -y ddev drush cr

Sanitize for local (optional)

本地环境数据清理（可选）

ddev drush sql-sanitize -y

undefined

ddev drush sql-sanitize -y

undefined

Daily Development Workflow

日常开发工作流

bash

undefined

bash

undefined

Morning: Start project

早上：启动项目

ddev start

Pull latest code

拉取最新代码

git pull origin main

Update dependencies if needed

如有需要，更新依赖

ddev composer install

Clear cache

清除缓存

ddev drush cr

Work on features...

开发功能...

Create database snapshot before testing

测试前创建数据库快照

ddev snapshot --name=before-testing

Test changes...

测试变更...

If needed, restore snapshot

如有需要，恢复快照

ddev snapshot restore --name=before-testing

Evening: Stop project

晚上：停止项目

ddev stop

---

ddev stop

---

Debugging with Xdebug

使用Xdebug调试

bash

undefined

bash

undefined

Enable Xdebug

启用Xdebug

ddev xdebug on

Run your debugger in IDE (PHPStorm, VSCode)

在IDE中启动调试器（PHPStorm、VSCode）

Set breakpoints and refresh page

设置断点并刷新页面

Disable when done (improves performance)

调试完成后禁用（提升性能）

ddev xdebug off

Check Xdebug status

查看Xdebug状态

ddev xdebug status


**VSCode launch.json**:
```json
{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

ddev xdebug status


**VSCode launch.json配置**：
```json
{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/var/www/html": "${workspaceFolder}"
  }
}

Performance Optimization

性能优化

macOS Performance (Mutagen)

macOS性能优化（Mutagen）

yaml

undefined

yaml

undefined

.ddev/config.yaml

performance_mode: mutagen


```bash

performance_mode: mutagen


```bash

Restart after config change

修改配置后重启

ddev restart

undefined

ddev restart

undefined

NFS Mount (Alternative for macOS)

NFS挂载（macOS替代方案）

yaml

undefined

yaml

undefined

.ddev/config.yaml

nfs_mount_enabled: true

undefined

nfs_mount_enabled: true

undefined

Database Tuning

数据库调优

yaml

undefined

yaml

undefined

.ddev/config.yaml

database: type: mariadb version: "10.6"

Create .ddev/mysql/my.cnf

创建.ddev/mysql/my.cnf

[mysqld] innodb_buffer_pool_size = 512M innodb_log_file_size = 128M

---

[mysqld] innodb_buffer_pool_size = 512M innodb_log_file_size = 128M

---

Custom Commands

自定义命令

Create project-specific commands in

.ddev/commands/web/

Example:

.ddev/commands/web/fresh-install

bash

#!/bin/bash

在

.ddev/commands/web/

目录下创建项目专属命令：

示例：

.ddev/commands/web/fresh-install

bash

#!/bin/bash

Description: Fresh Drupal install from scratch

Usage: fresh-install

Example: ddev fresh-install

set -e

echo "Installing fresh Drupal site..."

set -e

echo "Installing fresh Drupal site..."

Drop existing database

drush sql-drop -y

Install Drupal

drush site:install standard
--site-name="My Site"
--account-name=admin
--account-pass=admin
-y

Import config if exists

if [ -d /var/www/html/config/default ]; then drush config:import -y fi

Clear cache

drush cr

echo "Fresh install complete!" echo "Login: admin / admin"


Make it executable:
```bash
chmod +x .ddev/commands/web/fresh-install
ddev fresh-install

drush cr

echo "Fresh install complete!" echo "Login: admin / admin"


设置可执行权限：
```bash
chmod +x .ddev/commands/web/fresh-install
ddev fresh-install

Best Practices

最佳实践

Commit .ddev/config.yaml - Share config with team
Use ddev composer instead of local composer
Don't commit database snapshots - Too large
Create snapshots before risky operations
Disable Xdebug when not debugging - Performance impact
Use mutagen on macOS - Much faster file sync
Regular ddev poweroff - Free up system resources
Version pin services - PHP, database, Node.js
Use hooks for automation - Post-start tasks
Document custom commands - Help team members

提交.ddev/config.yaml - 与团队共享配置
使用ddev composer 而非本地composer
不要提交数据库快照 - 文件过大
执行高风险操作前创建快照
不调试时禁用Xdebug - 避免影响性能
在macOS上使用Mutagen - 文件同步速度更快
定期执行ddev poweroff - 释放系统资源
固定服务版本 - PHP、数据库、Node.js
使用钩子实现自动化 - 启动后任务
文档化自定义命令 - 帮助团队成员理解使用

Common Issues

常见问题

Site Not Loading

站点无法加载

bash

undefined

bash

undefined

Restart project

重启项目

ddev restart

Check status

查看状态

ddev describe

View logs

查看日志

ddev logs

Clear Drupal cache

清除Drupal缓存

ddev drush cr

undefined

ddev drush cr

undefined

Database Connection Error

数据库连接错误

bash

undefined

bash

undefined

Check database is running

检查数据库是否运行

ddev describe

Verify settings.php or settings.ddev.php exists

验证settings.php或settings.ddev.php是否存在

ddev ssh ls web/sites/default/settings*.php

undefined

ddev ssh ls web/sites/default/settings*.php

undefined

Port Conflicts

端口冲突

bash

undefined

bash

undefined

Stop all DDEV projects

停止所有DDEV项目

ddev poweroff

Check for port conflicts

检查端口冲突

lsof -i :80 -i :443

Change router HTTP port if needed

如有需要，修改路由器HTTP端口

ddev config --router-http-port=8080 --router-https-port=8443

undefined

ddev config --router-http-port=8080 --router-https-port=8443

undefined

Slow Performance on macOS

macOS上性能缓慢

bash

undefined

bash

undefined

Enable mutagen

启用Mutagen

ddev config --performance-mode=mutagen ddev restart

Or use NFS

或使用NFS

ddev config --nfs-mount-enabled=true ddev restart

undefined

ddev config --nfs-mount-enabled=true ddev restart

undefined

PHP Deprecation Warnings in Drush

Drush中出现PHP废弃警告

If you're seeing PHP deprecation warnings when running Drush commands (especially with PHP 8.4), create a custom PHP configuration file to suppress them:

.ddev/php/drush.ini
:

ini

; Suppress PHP deprecation warnings for Drush commands
[PHP]
error_reporting = 22527
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /tmp/php-errors.log

Then restart DDEV:

bash

ddev restart

How it works:

error_reporting = 22527

equals

E_ALL & ~E_DEPRECATED

```
display_errors = Off
```
prevents warnings from appearing on STDERR
```
display_startup_errors = Off
```
suppresses bootstrap warnings
Errors are logged to
```
/tmp/php-errors.log
```
instead of being displayed

This configuration applies to both web and CLI contexts since DDEV copies

.ddev/php/*.ini

files to both

/etc/php/[version]/cli/conf.d/

and

/etc/php/[version]/fpm/conf.d/

如果在执行Drush命令时看到PHP废弃警告（尤其是PHP 8.4版本），创建自定义PHP配置文件来抑制警告：

.ddev/php/drush.ini
：

ini

; Suppress PHP deprecation warnings for Drush commands
[PHP]
error_reporting = 22527
display_errors = Off
display_startup_errors = Off
log_errors = On
error_log = /tmp/php-errors.log

然后重启DDEV：

bash

ddev restart

工作原理：

error_reporting = 22527

等同于

E_ALL & ~E_DEPRECATED

```
display_errors = Off
```
防止警告出现在STDERR中
```
display_startup_errors = Off
```
抑制启动阶段的警告
错误将记录到
```
/tmp/php-errors.log
```
而非直接显示

此配置同时适用于Web和CLI环境，因为DDEV会将

.ddev/php/*.ini

文件复制到

/etc/php/[version]/cli/conf.d/

和

/etc/php/[version]/fpm/conf.d/

目录。

Docker Desktop overlay2 I/O Errors

Docker Desktop overlay2 I/O错误

If Docker Desktop gets into a bad state producing overlay2 or containerd I/O errors such as:

Error response from daemon: error creating temporary lease: write /var/lib/desktop-containerd/daemon/io.containerd.metadata.v1.bolt/meta.db: input/output error

Error response from daemon: open /var/lib/docker/overlay2/...: input/output error

A normal quit and restart of Docker Desktop is not sufficient. You must force quit ALL Docker processes (via Activity Monitor or

killall -9 Docker

killall -9 com.docker.hyperkit

), then relaunch Docker Desktop. Only a full force quit clears the corrupted state.

如果Docker Desktop出现异常状态，产生overlay2或containerd I/O错误，例如：

Error response from daemon: error creating temporary lease: write /var/lib/desktop-containerd/daemon/io.containerd.metadata.v1.bolt/meta.db: input/output error

Error response from daemon: open /var/lib/docker/overlay2/...: input/output error

仅正常退出并重启Docker Desktop是不够的。您必须强制终止所有Docker进程（通过活动监视器或执行

killall -9 Docker

killall -9 com.docker.hyperkit

），然后重新启动Docker Desktop。只有完全强制终止才能清除损坏的状态。

Unhealthy Containers / Mutagen Sync Hanging

容器状态异常/Mutagen同步挂起

After Docker crashes or force-quits, DDEV can get into a bad state where:

```
ddev start
```
hangs at "Starting Mutagen sync process..."
Web container reports unhealthy (
```
phpstatus:FAILED
```
,
```
mailpit:FAILED
```
)
```
ddev mutagen reset
```
fails with "CreateOrResumeMutagenSync Failure"

Fix (run in order):

bash

undefined

Docker崩溃或强制退出后，DDEV可能进入异常状态，表现为：

```
ddev start
```
在"Starting Mutagen sync process..."步骤挂起
Web容器报告状态异常（
```
phpstatus:FAILED
```
,
```
mailpit:FAILED
```
）
```
ddev mutagen reset
```
失败并提示"CreateOrResumeMutagenSync Failure"

修复步骤（按顺序执行）：

bash

undefined

1. Full power off to clean up all containers and networks

1. 完全关闭所有容器和网络

ddev poweroff

2. Start fresh

2. 重新启动

ddev start


If `ddev poweroff` doesn't resolve it:

```bash

ddev start


如果`ddev poweroff`无法解决问题：

```bash

1. Stop DDEV

1. 停止DDEV

ddev stop

2. Reset the Mutagen daemon

2. 重置Mutagen守护进程

~/.ddev/bin/mutagen daemon stop ~/.ddev/bin/mutagen daemon start

3. Reset Mutagen sync (removes Docker volume, forces full resync)

3. 重置Mutagen同步（删除Docker卷，强制完全重新同步）

ddev mutagen reset

4. Start fresh

4. 重新启动

ddev start


**Monitoring commands** while troubleshooting:
```bash
ddev mutagen status -l      # Detailed sync status
ddev mutagen monitor        # Real-time sync progress
docker inspect --format "{{ json .State.Health }}" ddev-<project>-web  # Container health

ddev start


**故障排查时的监控命令**：
```bash
ddev mutagen status -l      # 详细同步状态
ddev mutagen monitor        # 实时同步进度
docker inspect --format "{{ json .State.Health }}" ddev-<project>-web  # 容器健康状态

Multi-Project Management

多项目管理

bash

undefined

bash

undefined

List all projects

列出所有项目

ddev list

Stop all projects

停止所有项目

ddev poweroff

Remove stopped projects

删除已停止的项目

ddev delete <project-name>

Remove all project containers (keep files)

删除所有项目容器（保留文件）

ddev delete --omit-snapshot --yes <project-name>

---

ddev delete --omit-snapshot --yes <project-name>

---