ddev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

DDEV for Craft CMS Development

用于Craft CMS开发的DDEV指南

Documentation

参考文档

DDEV docs: https://docs.ddev.com/en/stable/
Craft CMS quickstart: https://docs.ddev.com/en/stable/users/quickstart/#craft-cms
Configuration reference: https://docs.ddev.com/en/stable/users/configuration/config/
Custom commands: https://docs.ddev.com/en/stable/users/extend/custom-commands/
Additional services: https://docs.ddev.com/en/stable/users/extend/additional-services/
Vite integration: https://docs.ddev.com/en/stable/users/usage/developer-tools/#nodejs

When unsure about a DDEV feature,

web_fetch

the relevant docs page.

DDEV官方文档: https://docs.ddev.com/en/stable/
Craft CMS快速上手: https://docs.ddev.com/en/stable/users/quickstart/#craft-cms
配置参考: https://docs.ddev.com/en/stable/users/configuration/config/
自定义命令: https://docs.ddev.com/en/stable/users/extend/custom-commands/
额外服务: https://docs.ddev.com/en/stable/users/extend/additional-services/
Vite集成: https://docs.ddev.com/en/stable/users/usage/developer-tools/#nodejs

如果你不确定某个DDEV功能的用法，可以通过

web_fetch

获取对应文档页面的内容。

Common Pitfalls

常见误区

Using
```
ddev exec composer install
```
instead of
```
ddev composer install
```
— DDEV shorthand commands handle path resolution and environment setup. Always use the shorthand.
Forgetting
```
ddev craft up
```
does both
```
migrate/all
```
and
```
project-config/apply
```
— no need to run them separately after pulls or deploys.
Exposing the Vite dev server with
```
ports
```
instead of
```
web_extra_exposed_ports
```
—
```
ports
```
causes conflicts when running multiple DDEV projects.
```
web_extra_exposed_ports
```
routes through Traefik and works with HTTPS.
Running
```
ddev composer global require
```
— global packages install inside the container and vanish on restart. Install project-level dependencies only.
Setting
```
nodejs_version
```
but running
```
npm install
```
on the host — Node must run inside the container via
```
ddev npm
```
to match the configured version.
Editing
```
.ddev/config.yaml
```
while containers are running without restarting — changes to config require
```
ddev restart
```
to take effect.
Using
```
ddev import-db
```
without
```
--target-db=db
```
on multi-database setups — the default target is
```
db
```
, but if you've configured additional databases, be explicit.
Missing
```
#ddev-generated
```
comment in custom commands — without it, DDEV won't manage or update the file.

使用
```
ddev exec composer install
```
而不是
```
ddev composer install
```
——DDEV的简写命令会自动处理路径解析和环境配置，请始终使用简写命令。
忘记
```
ddev craft up
```
会同时执行
```
migrate/all
```
和
```
project-config/apply
```
——拉取代码或部署后无需单独运行这两个命令。
使用
```
ports
```
而不是
```
web_extra_exposed_ports
```
暴露Vite开发服务端口——运行多个DDEV项目时
```
ports
```
会导致冲突，
```
web_extra_exposed_ports
```
通过Traefik路由，支持HTTPS，兼容性更好。
运行
```
ddev composer global require
```
——全局包会安装在容器内部，重启后就会消失，请仅安装项目级别的依赖。
设置了
```
nodejs_version
```
但在宿主机运行
```
npm install
```
——必须通过
```
ddev npm
```
在容器内运行Node相关命令，才能匹配配置的Node版本。
容器运行时修改
```
.ddev/config.yaml
```
后没有重启——配置修改需要执行
```
ddev restart
```
才能生效。
多数据库配置场景下使用
```
ddev import-db
```
时没有添加
```
--target-db=db
```
参数——默认目标库是
```
db
```
，如果你配置了额外的数据库，需要明确指定目标库。
自定义命令中缺少
```
#ddev-generated
```
注释——没有这个注释的话，DDEV不会管理和更新该文件。

Shorthand Commands

简写命令

Always use DDEV shorthand over

ddev exec

bash

ddev composer install          # not ddev exec composer install
ddev craft up                  # not ddev exec php craft up
ddev npm install               # not ddev exec npm install
ddev craft make service        # scaffolding

请始终使用DDEV简写命令，不要使用

ddev exec

：

bash

ddev composer install          # 不要用ddev exec composer install
ddev craft up                  # 不要用ddev exec php craft up
ddev npm install               # 不要用ddev exec npm install
ddev craft make service        # 代码生成

Craft CMS Project Type

Craft CMS项目配置类型

yaml

undefined

yaml

undefined

.ddev/config.yaml

name: my-craft-site type: craftcms docroot: web php_version: "8.3" database: type: mysql version: "8.0" nodejs_version: "20"


DDEV auto-injects: `CRAFT_DB_SERVER`, `CRAFT_DB_USER`, `CRAFT_DB_PASSWORD`, `CRAFT_DB_DATABASE`, `PRIMARY_SITE_URL`.

name: my-craft-site type: craftcms docroot: web php_version: "8.3" database: type: mysql version: "8.0" nodejs_version: "20"


DDEV会自动注入以下环境变量：`CRAFT_DB_SERVER`、`CRAFT_DB_USER`、`CRAFT_DB_PASSWORD`、`CRAFT_DB_DATABASE`、`PRIMARY_SITE_URL`。

Common Commands

常用命令

bash

ddev start                     # Start the project
ddev stop                      # Stop the project
ddev restart                   # Restart containers
ddev ssh                       # SSH into web container
ddev describe                  # Show project info and URLs
ddev logs                      # View container logs
ddev import-db --file=dump.sql # Import database
ddev export-db --file=dump.sql # Export database
ddev xdebug on                 # Enable Xdebug
ddev craft db/backup           # Craft database backup

bash

ddev start                     # 启动项目
ddev stop                      # 停止项目
ddev restart                   # 重启容器
ddev ssh                       # SSH登录到web容器
ddev describe                  # 展示项目信息和访问URL
ddev logs                      # 查看容器日志
ddev import-db --file=dump.sql # 导入数据库
ddev export-db --file=dump.sql # 导出数据库
ddev xdebug on                 # 启用Xdebug
ddev craft db/backup           # Craft数据库备份

Post-Install Auto-Run

安装后自动执行脚本

Composer scripts auto-run

craft up

after install/update:

json

{
    "scripts": {
        "post-craft-update": [
            "@php craft install/check && php craft up --interactive=0 || exit 0"
        ],
        "post-update-cmd": "@post-craft-update",
        "post-install-cmd": "@post-craft-update"
    }
}

No need to manually run

ddev craft migrate/all

ddev craft project-config/apply

—

ddev craft up

does both, and it auto-runs after

ddev composer install/update

Composer脚本会在安装/更新依赖后自动运行

craft up

：

json

{
    "scripts": {
        "post-craft-update": [
            "@php craft install/check && php craft up --interactive=0 || exit 0"
        ],
        "post-update-cmd": "@post-craft-update",
        "post-install-cmd": "@post-craft-update"
    }
}

无需手动运行

ddev craft migrate/all

或

ddev craft project-config/apply

——

ddev craft up

会同时执行这两个操作，并且会在

ddev composer install/update

执行后自动触发。

Add-ons

扩展插件

bash

ddev add-on get ddev/ddev-redis       # Install Redis
ddev add-on get ddev/ddev-mailpit     # Install Mailpit
ddev add-on list                       # List installed add-ons
ddev add-on remove ddev/ddev-redis    # Remove add-on

bash

ddev add-on get ddev/ddev-redis       # 安装Redis
ddev add-on get ddev/ddev-mailpit     # 安装Mailpit
ddev add-on list                       # 列出已安装的扩展
ddev add-on remove ddev/ddev-redis    # 卸载扩展

Custom Commands

自定义命令

Place scripts in

.ddev/commands/web/

(container) or

.ddev/commands/host/

(host):

bash

#!/usr/bin/env bash

将脚本放在

.ddev/commands/web/

（容器内执行）或

.ddev/commands/host/

（宿主机执行）路径下：

bash

#!/usr/bin/env bash

Description: Run ECS code style check

Usage: check-cs

Example: ddev check-cs

#ddev-generated

cd /var/www/html && composer check-cs

undefined

#ddev-generated

cd /var/www/html && composer check-cs

undefined

Troubleshooting

问题排查

bash

ddev poweroff                  # Stop all DDEV projects
ddev debug router              # Debug router configuration
ddev debug capabilities        # Check Docker capabilities
ddev delete --omit-snapshot    # Remove project without snapshot

bash

ddev poweroff                  # 停止所有DDEV项目
ddev debug router              # 调试路由配置
ddev debug capabilities        # 检查Docker能力
ddev delete --omit-snapshot    # 删除项目且不生成快照