ddev

DDEV

DDEV 是一款基于 Docker 的 PHP/Node 项目本地开发工具。它封装了常用的命令行工具（composer、npm、wp、drush 等），让它们可以在容器内运行，无需在本地安装。完整文档：https://docs.ddev.com

CLI 语法糖

DDEV 提供快捷命令，可代理调用容器内部的工具。请使用这些命令，而不是 ddev exec：

ddev composer install          # runs composer inside the container
ddev npm run build             # runs npm inside the container
ddev wp plugin list            # runs wp-cli (WordPress only)
ddev drush cr                  # runs drush (Drupal only)
ddev artisan migrate           # runs artisan (Laravel only)
ddev console cache:clear       # runs bin/console (Symfony only)
ddev yarn add <pkg>            # runs yarn inside the container
ddev php -v                    # runs PHP inside the container

如需查看快捷命令及其映射的完整列表，请运行 ddev help。

可在任意子目录中运行 DDEV 命令

DDEV 会自动从项目树中的任意子目录检测项目根目录。无论 shell 当前位于哪个目录，大多数 DDEV 命令都可以直接运行：

ddev wp plugin list
ddev mailpit
ddev db
ddev composer show
ddev npm ls
ddev drush cr
ddev start
ddev describe
ddev ssh

运行这些命令无需特殊标志或路径解析。

需要使用 --dir 指定作用范围的情况

只有在通过 ddev exec 运行对文件路径敏感的脚本，且必须将其作用范围限定到容器内的特定子目录时，才需要 --dir 标志。这适用于会基于工作目录操作文件的命令（例如，读取特定 composer.json 的 composer install，或读取特定 package.json 的 npm install）。

步骤 1：解析容器路径

运行随附的解析脚本，将主机上的子目录映射到容器路径：

scripts/resolve-ddev-root.sh "$(pwd)"

输出（JSON）：

{
  "project_root": "/Users/you/Projects/mysite",
  "container_path": "/var/www/html/wp-content/plugins/my-plugin",
  "relative_path": "wp-content/plugins/my-plugin",
  "project_name": "mysite"
}

• relative_path 为空——工作目录就是 DDEV 根目录，无需使用 --dir。
• relative_path 非空——对于对文件路径敏感的命令，请将 container_path 的值与 --dir 一起使用。

步骤 2：运行限定范围的命令

如果 DDEV 尚未运行，请先使用 ddev start 启动。

# Install dependencies scoped to a plugin subdirectory
ddev exec --dir="/var/www/html/wp-content/plugins/my-plugin" bash -c "composer install"
ddev exec --dir="/var/www/html/wp-content/plugins/my-plugin" bash -c "npm install"

# Run a script that reads files relative to the working directory
ddev exec --dir="/var/www/html/wp-content/plugins/my-plugin" bash -c "phpunit"

如果不使用 --dir，这些命令会在容器文档根目录（/var/www/html）中运行，并操作错误的 composer.json、package.json 或项目上下文。

在容器中运行命令

没有快捷命令可用，或需要指定容器目录时，请使用 ddev exec：

# Runs in web container at docroot
ddev exec ls -la

# Scope to a subdirectory for file-path-sensitive operations
ddev exec --dir="/var/www/html/wp-content/plugins/my-plugin" bash -c "composer install"

# Run in the database container
ddev exec -s db mysql -e "SHOW DATABASES"

# Shorthand alias
ddev . ls -la

子路径映射（用于 ddev exec --dir）

只有在使用 ddev exec --dir 将对文件路径敏感的脚本限定到某个子目录时，才需要解析路径。标准 DDEV 命令（ddev wp、ddev mailpit、ddev db、ddev start 等）无需此操作——它们可自动从任意子目录运行。

解析 DDEV 根目录

使用随附的解析脚本查找 DDEV 项目根目录并计算容器路径：

# From any subdirectory within a DDEV project
scripts/resolve-ddev-root.sh /path/to/wp-content/plugins/my-plugin

该脚本会逐级向上遍历目录树，查找 .ddev/config.yaml。如果未提供参数，则使用当前工作目录。

手动计算路径

如果脚本不可用，请手动计算路径：

1. 找到包含 .ddev/config.yaml 的目录（DDEV 项目根目录）
2. 计算从该根目录到当前工作目录的相对路径
3. 在路径前添加 /var/www/html/，得到容器路径

项目信息

使用 ddev describe 获取当前 DDEV 项目的详细信息。添加 -j 标志以获取结构化 JSON 输出：

ddev describe -j

此命令会提供以下实用信息：

• 项目类型（wordpress、drupal、laravel 等）
• 主要 URL 和所有项目 URL
• PHP 版本和 Node.js 版本
• 数据库类型和版本（mariadb、mysql、postgres）
• Web 服务器类型（nginx-fpm、apache-fpm）
• Web、db 和其他服务的服务状态
• 用于主机与容器之间映射的已发布端口

JSON 输出字段示例：

• type - 项目类型（wordpress、drupal 等）
• primary_url - 项目主 URL
• urls - 所有项目 URL（HTTP 和 HTTPS）的数组
• php_version - 使用的 PHP 版本
• nodejs_version - 使用的 Node.js 版本
• database_type - 数据库类型（mariadb、mysql、postgres）
• webserver_type - Web 服务器（nginx-fpm、apache-fpm）
• services - 各项服务的状态和详细信息

资源

scripts/

• resolve-ddev-root.sh - 从任意子目录逐级向上遍历目录树，查找 DDEV 项目根目录。返回包含项目根目录、容器路径、相对路径和项目名称的 JSON。

references/

• npm-projects.md - 在 DDEV 中运行 npm/Node.js 开发服务，包括端口公开、主机绑定，以及 Vite、Next.js 和 Astro 的框架专属示例。
• wordpress-multisite.md - 使用 DDEV 配置 WordPress Multisite 的指南，涵盖子域名、不同的主机名，以及使用 WP-CLI 命令配置子目录。