Drupal 9本地开发最佳实践：DDEV+Docker一站式环境搭建

1. 项目概述：为什么本地用 Docker + DDEV 搭建 Drupal 9 环境是当前最稳的开发起点

你是不是也经历过这样的场景：刚接手一个 Drupal 9 项目，团队给了一堆 composer.json 、 settings.php 和 .ddev 配置，但你的本地环境要么 PHP 版本不对（Drupal 9.5+ 要求 PHP 8.0+），要么 MySQL 版本太老（不支持 JSON 字段），要么 Apache 模块没开全（mod_rewrite、mod_headers 缺一不可），折腾半天 drush cr 报错、 /admin 页面白屏、甚至 composer install 直接卡死在 symfony/yaml 的扩展检测上？我试过在 macOS 上手动编译 PHP 8.2、在 Windows WSL2 里反复重装 MariaDB、也在 Ubuntu 22.04 上被 php-sqlite3 扩展缺失坑了整整一个下午——直到我把整套环境交给 DDEV + Docker，才真正把“环境问题”从每日待办清单里划掉。

这个标题直指一个非常具体、高频、且极具实操价值的技术组合： Drupal 9 + 本地开发 + Docker 容器化 + DDEV 工具链 。它不是泛泛而谈“如何学 Drupal”，而是精准锁定“如何让 Drupal 9 在你自己的笔记本上，像生产环境一样可靠、可复现、可协作地跑起来”。关键词 Drupal 9 决定了技术栈边界（PHP 8.0–8.2、MySQL 5.7+/MariaDB 10.3+、Apache/Nginx + mod_rewrite）； Docker 是底层虚拟化基石，解决“系统依赖隔离”这一根本矛盾； DDEV 则是面向 Drupal（及 WordPress、TYPO3 等 PHP CMS）深度优化的开发平台，它把 Docker 的复杂性封装成几条命令，同时内置了 Drupal 专用的调试钩子、数据库同步、文件共享策略和 HTTPS 代理。而 entornos locales （本地环境）这个西班牙语词，恰恰点明了核心诉求： 不依赖远程服务器、不依赖同事的配置、不依赖公司统一镜像——你的电脑就是生产环境的最小可信副本 。

适合谁看？如果你是刚从 Drupal 7 升级过来的开发者，对 Composer 依赖管理还不熟；如果你是前端工程师，需要快速拉起后端环境联调 Twig 模板和 REST API；如果你是运维新手，想理解容器化如何替代传统 LAMP 堆栈；甚至如果你是项目经理，需要向客户解释“为什么我们开发环境必须和线上一致”——这篇文章都给你准备好了可验证、可截图、可复现的完整路径。接下来所有内容，全部基于真实项目落地经验：从零安装、首次启动、模块启用、多语言配置，到排查 502 Bad Gateway 、修复 vendor/autoload.php not found 、绕过国内网络限制拉取镜像——没有理论空谈，只有键盘敲出来的每一步。

2. 整体设计思路：为什么放弃 MAMP/XAMPP/Laragon，坚定选择 DDEV + Docker

2.1 不是“又一种本地环境工具”，而是为 Drupal 量身定制的开发协议

很多人第一次看到 DDEV，会下意识把它和 MAMP、Laragon 或 XAMPP 归为一类——都是“点开图标就能跑 PHP”的本地套件。这是最大的误解。MAMP 是把 Apache、PHP、MySQL 打包进一个 macOS 应用；XAMPP 是 Windows 下的类似方案；它们本质仍是 进程级共存 ：PHP 进程跑在宿主机上，MySQL 数据库文件存在 C:\xampp\mysql\data 里，所有服务共享同一套系统库。而 DDEV 的底层是 Docker，这意味着：

• 每个项目拥有独立的、不可变的运行时环境 ：你的 Drupal 9 项目用 PHP 8.1 + MySQL 8.0 + Nginx，隔壁的 Laravel 项目用 PHP 8.2 + PostgreSQL 14 + Apache，它们互不干扰，哪怕你同时启动十个 DDEV 项目，资源占用也远低于一个 MAMP 实例。
• 环境定义即代码（Infrastructure as Code） ： .ddev/config.yaml 文件明确声明了 PHP 版本、Web 服务器类型、数据库类型、端口映射、自定义命令等。这个文件可以提交到 Git，新同事 git clone && ddev start 就能获得和你完全一致的环境——而 MAMP 的配置藏在图形界面里，无法版本化。
• Drupal 深度集成是刚需，不是锦上添花 ：DDEV 内置了 ddev drush 、 ddev drush sql:sync 、 ddev drush cim 等命令，它知道 Drupal 的 webroot 在 web/ 还是 docroot/ ，能自动识别 settings.local.php 并注入开发配置（如禁用缓存、开启错误报告），甚至能一键生成 drush 别名供远程同步使用。MAMP 只提供一个空白 PHP 环境，你要自己配 Drush、自己写 settings.local.php 、自己处理 trusted_host_patterns ——这些在 DDEV 里全是开箱即用。

提示：DDEV 的核心价值不是“比 MAMP 多了 Docker”，而是它把 Drupal 开发中那些重复、易错、难协作的环境配置动作，全部标准化、自动化、可审计化。当你在 .ddev/config.yaml 里写下 php_version: "8.1" ，你不是在选一个版本，而是在签署一份环境契约：从此这个项目的 PHP 行为，将严格遵循 PHP 8.1 的 RFC 规范，包括 str_contains() 函数是否存在、 match 表达式语法是否合法、以及 DateTime::createFromImmutable() 是否可用——这些细节，直接决定你的模块能否通过 Drupal 9.5 的兼容性检查。

2.2 Docker 为何不可替代？从三个真实故障说起

有人问：“我的 Mac 已经装了 Homebrew PHP 8.1，为什么还要 Docker？” 我用三个项目现场故障回答：

故障一：PHP 扩展冲突
项目 A 要求 gd 扩展带 WebP 支持，项目 B 要求 imagick 扩展用 ImageMagick 7。Homebrew 只能全局安装一个 php-gd ，你改一次 brew reinstall php@8.1 --with-webp ，项目 B 就报 Class 'Imagick' not found 。Docker 中，每个项目镜像都预装好所需扩展： ddev/php-8.1-webp 镜像含 WebP， ddev/php-8.1-imagemagick 含 Imagick，切换只需改一行 php_version 配置。

故障二：MySQL 字符集陷阱
Drupal 9 默认要求 utf8mb4 字符集，但 macOS 自带的 MySQL 5.7 默认 collation_server=utf8mb4_unicode_ci ，而某些旧版 Drupal 模块（如 pathauto ）的 SQL 查询会因 utf8mb4 的索引长度限制失败。你在宿主机上改 my.cnf ，可能影响其他项目；在 Docker 里，DDEV 的 mysql 服务镜像已预设 character-set-server=utf8mb4 和 collation-server=utf8mb4_unicode_ci ，且 innodb_large_prefix=ON ，开箱即合规。

故障三：Composer 依赖地狱
drupal/core-recommended 要求 symfony/http-foundation:^5.4 ，但你的全局 Composer 用的是 ^6.0 。宿主机上 composer update 会报冲突；DDEV 中， ddev composer 命令在容器内执行，使用的是镜像内置的 Composer 2.5+ 和精确匹配的 Symfony 版本， vendor/ 目录完全隔离，不会污染宿主机。

注意：DDEV 的 Docker 镜像不是通用 Linux 发行版，而是专为 PHP CMS 优化的精简镜像。它去掉了 apt-get update 、 systemd 、 cron 等无关组件，只保留 apache2 , nginx , php-fpm , mysql-client , drush , composer 等必需项。这使得镜像体积小（PHP 8.1 镜像仅 280MB）、启动快（平均 3.2 秒）、内存占用低（空闲时 120MB）。你不需要成为 Docker 专家，但必须理解：DDEV 的价值，始于 Docker 提供的确定性，成于它对 Drupal 场景的深度适配。

2.3 DDEV vs Lando vs Docksal：为什么选 DDEV？

市场上还有 Lando 和 Docksal 两个同类工具。我对比过它们在 Drupal 9 项目中的实际表现：

结论很清晰：如果你的目标是 最快、最稳、最少配置地让 Drupal 9 在本地跑起来，并长期维护多个 Drupal 项目 ，DDEV 是目前唯一一个把“Drupal 开发者体验”做到产品级的工具。它不追求 Docker 技术炫技，而是把 90% 的常见问题（HTTPS、邮件发送、数据库导入、文件上传）封装成一条命令，让你专注写模块、调样式、测 API。

3. 核心细节解析：DDEV 配置文件、目录结构与 Drupal 9 专属约定

3.1 .ddev/config.yaml 的每一行都在解决什么问题？

DDEV 的灵魂是 .ddev/config.yaml 。这不是一个可有可无的配置文件，而是整个本地环境的“宪法”。我们逐行拆解一个典型的 Drupal 9 项目配置：

# .ddev/config.yaml
name: my-drupal-site
type: drupal9
docroot: "web"
php_version: "8.1"
webserver_type: nginx-fpm
database: mariadb:10.6
use_dns_when_possible: true
additional_fqdns: []
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
web_environment: []

• name: my-drupal-site ：项目唯一标识，DDEV 用它生成容器名（如 ddev-my-drupal-site-web ）、数据库名（ db ）、以及 HTTPS 证书域名（ my-drupal-site.ddev.site ）。 命名不能含下划线 _ ，否则 Docker 会报错 invalid container name 。
• type: drupal9 ：这是最关键的字段。它告诉 DDEV：“请按 Drupal 9 的最佳实践初始化环境”。DDEV 会自动：
  • 创建 settings.local.php 并注入 error_level = ERROR_REPORTING_DISPLAY_ALL ；
  • 设置 trusted_host_patterns 为 ['^my\-drupal\-site\.ddev\.site$'] ；
  • 启用 opcache.revalidate_freq=0 （禁用 OPCache 缓存）；
  • 配置 Nginx 的 location ~ \.php$ 块，正确传递 SCRIPT_FILENAME 。
    如果你写 type: php ，DDEV 就不会做这些 Drupal 专属操作，你得自己手写 settings.local.php 和 Nginx 配置。
• docroot: "web" ：Drupal 9 推荐的目录结构（ composer create-project drupal/recommended-project 生成），Web 根目录是 web/ 子目录，而非项目根目录。DDEV 会把 web/ 挂载为 Web 服务器的 DocumentRoot 。如果项目是旧版 Drupal（ docroot/ 或根目录），这里要改成 "docroot" 或 "." 。
• php_version: "8.1" ：DDEV 支持 PHP 7.4–8.2，但 Drupal 9.5+ 强制要求 PHP 8.0+ 。选 8.1 是因为：
  • 它是 Drupal 9.5 的最低推荐版本，兼容所有核心模块；
  • 8.2 虽新，但部分第三方模块（如 devel 4.x）尚未完全适配；
  • 8.0 已 EOL（End of Life），安全更新已停止。
• webserver_type: nginx-fpm ：Nginx + PHP-FPM 组合比 Apache 更轻量，DDEV 的 Nginx 配置已针对 Drupal 9 优化，包含 try_files $uri /index.php?$query_string 和 fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name ，完美支持 Clean URLs。
• database: mariadb:10.6 ：MariaDB 10.6 是 Drupal 9.5 的推荐数据库，它原生支持 JSON 字段（ config 表存储）、 utf8mb4_0900_as_cs 排序规则（区分大小写），且性能优于 MySQL 5.7。DDEV 的 mariadb:10.6 镜像已预设 character-set-server=utf8mb4 和 collation-server=utf8mb4_unicode_ci 。

实操心得：每次新建项目，我必做的三件事是：① ddev config --project-type=drupal9 --docroot=web --php-version=8.1 自动生成配置；② ddev start 启动后立即 ddev exec drush status ，确认 Drupal version 和 PHP configuration 显示正确；③ ddev describe 查看所有服务端口和 URL，确保 https://my-drupal-site.ddev.site 可访问。这三步能在 2 分钟内验证环境基础是否健康。

3.2 目录结构：为什么 web/ 是黄金标准？

Drupal 9 推荐的目录结构如下（由 composer create-project drupal/recommended-project 生成）：

my-drupal-site/
├── composer.json          # 项目依赖定义
├── web/                   # Web 根目录（必须）
│   ├── index.php          # Drupal 入口
│   ├── sites/             # settings.php, modules/, themes/
│   └── core/              # Drupal 核心（由 Composer 管理）
├── vendor/                # Composer 依赖（不应提交 Git）
└── .ddev/                 # DDEV 配置

这个结构的价值在于 彻底分离 Web 可访问目录与项目源码 ：

• web/ 是唯一被 Web 服务器公开的目录， index.php 在此， sites/default/files 上传目录在此， robots.txt 和 .htaccess 也在此。攻击者即使拿到 Web Shell，也无法直接读取项目根目录下的 composer.json （含敏感配置）或 .ddev/config.yaml （含数据库密码）。
• core/ 、 vendor/ 、 .ddev/ 等目录位于 web/ 之外，Web 服务器默认禁止访问（DDEV 的 Nginx 配置已添加 location ~ ^/(vendor|core|modules|themes|profiles|libraries|includes|misc|scripts|sites|templates|web|README|CHANGELOG|INSTALL|LICENSE|MAINTAINERS)\b { deny all; } ）。
• sites/default/settings.php 中的 $settings['hash_salt'] 和数据库连接信息，应放在 sites/default/settings.local.php （由 DDEV 自动生成并 Git 忽略），避免泄露。

提示：如果你的旧项目是扁平结构（ index.php 在项目根目录），迁移至 web/ 结构只需三步：① mkdir web && mv index.php .htaccess robots.txt web/ ；② mv core/ modules/ profiles/ sites/ themes/ web/ ；③ 修改 web/sites/default/settings.php 中的 $settings['hash_salt'] 路径，将 ../ 改为 ../../ 。DDEV 会自动识别 web/ 并挂载为根目录，无需改 Nginx 配置。

3.3 Drupal 9 专属配置： settings.local.php 里的生存指南

DDEV 在 web/sites/default/settings.local.php 中注入的配置，是 Drupal 9 本地开发的“安全气囊”。我们来解读关键行：

// web/sites/default/settings.local.php
$databases['default']['default'] = [
  'database' => 'db',
  'username' => 'db',
  'password' => 'db',
  'host' => 'db',
  'port' => '3306',
  'driver' => 'mysql',
  'prefix' => '',
];
$settings['hash_salt'] = '...'; // DDEV 自动生成的随机盐值
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
$config['system.performance']['css']['preprocess'] = FALSE;
$config['system.performance']['js']['preprocess'] = FALSE;
$settings['error_level'] = ERROR_REPORTING_DISPLAY_ALL;
$settings['php_storage']['default']['directory'] = '/tmp';
$settings['skip_permissions_hardening'] = TRUE;

• $databases 数组： host 设为 'db' 是因为 DDEV 的数据库服务容器名就是 db ，Docker 内部 DNS 会自动解析 db 为数据库容器 IP。你不需要记 127.0.0.1 或 localhost ，DDEV 已为你做好服务发现。
• $settings['error_level'] = ERROR_REPORTING_DISPLAY_ALL ：强制显示所有 PHP 错误、警告、通知，包括 E_DEPRECATED （弃用警告）。Drupal 9 正在逐步淘汰 mysql_* 函数，这个设置能让你第一时间发现模块兼容性问题。
• $config['system.performance']['*']['preprocess'] = FALSE ：禁用 CSS/JS 聚合，确保你修改 theme.css 后刷新即生效，不用清缓存。
• $settings['skip_permissions_hardening'] = TRUE ：DDEV 的文件挂载机制（ bind mount ）在 Windows/macOS 上常导致 chmod 权限错误，此设置跳过 Drupal 的权限加固检查，避免 The file permissions could not be set on ... 报错。
• $settings['php_storage']['default']['directory'] = '/tmp' ：将 PHP OPcache、Twig 编译缓存等临时文件存到容器 /tmp 目录，而非宿主机 sites/default/files ，避免 Windows/macOS 文件系统权限问题。

注意： settings.local.php 不应提交到 Git 。DDEV 的 .gitignore 已包含 web/sites/*/settings.local.php 。如果你在团队中，应确保所有成员都运行 ddev start ，由 DDEV 自动创建该文件。手动编辑它可能导致环境不一致。

4. 实操过程：从零开始搭建、启动、配置 Drupal 9 本地环境

4.1 环境准备：Docker Desktop 与 DDEV 的安装要点

Docker Desktop 安装（Windows/macOS）

• Windows ：必须 Windows 10 Pro/Enterprise 22H2（Build 19045）或 Windows 11。Home 版本不支持 WSL2，无法运行 DDEV。下载 Docker Desktop for Windows ，安装时勾选 “Enable the WSL 2 based engine” 。安装后重启，打开 PowerShell 运行 wsl -l -v ，确认 WSL2 已启用。
• macOS ：Intel 芯片用 Docker Desktop for Mac (Intel) ，Apple Silicon（M1/M2）用 Docker Desktop for Mac (ARM64) 。安装后，在 Docker Desktop 设置中开启 “Use the new Virtualization framework” （macOS 13.3+ 必须开启）。
• Linux（Ubuntu/Debian） ：不推荐 Docker Desktop，直接用 apt 安装 Docker Engine：

  sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release
  sudo mkdir -p /etc/apt/keyrings
  curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
  echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
  sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
  sudo usermod -aG docker $USER
  

  提示：Linux 用户务必运行 sudo usermod -aG docker $USER 并重新登录，否则 ddev 会报 Permission denied while trying to connect to the Docker daemon socket 。

DDEV 安装

• macOS（Homebrew） ： brew tap drud/ddev && brew install ddev
• Windows（Chocolatey） ： choco install ddev
• Linux/通用 ： curl -LO https://raw.githubusercontent.com/drud/ddev/master/scripts/install_ddev.sh && bash install_ddev.sh
• 验证安装 ： ddev version 应输出 DDEV-Local version v1.22.4 （或更高）， docker version 应显示 Client 和 Server 版本均正常。

实操心得：我遇到最多的安装失败，90% 是 Docker Desktop 未启动或 WSL2 未启用。Windows 用户务必在 PowerShell 中运行 wsl -l -v ，确认状态为 Running ；macOS 用户在 Docker Desktop 图标右键菜单中确认 “Start Docker Desktop” 已勾选。不要跳过这一步，否则 ddev start 会卡在 Starting services... 。

4.2 创建 Drupal 9 项目：Composer 初始化与 DDEV 初始化

步骤 1：用 Composer 创建标准 Drupal 9 项目

# 创建项目目录
mkdir my-drupal-site && cd my-drupal-site

# 使用 Drupal 推荐项目模板（Drupal 9.5+）
composer create-project drupal/recommended-project .

# 等待完成（约 3–5 分钟，国内用户建议先配置 Composer 镜像）
# 完成后，目录结构为：./web/, ./vendor/, ./composer.json 等

提示：国内用户 Composer 拉取慢，务必提前配置阿里云镜像：
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
这能将 composer create-project 时间从 15 分钟缩短至 3 分钟。

步骤 2：初始化 DDEV 配置

# 在项目根目录运行
ddev config --project-type=drupal9 --docroot=web --php-version=8.1

# 输出：
# Created a new ddev project configuration in the current directory
# Configuration file written to .ddev/config.yaml
# You can now run 'ddev start' to start your site.

此时 .ddev/config.yaml 已生成，内容如前文所述。DDEV 还会自动创建 .ddev/.gitignore ，忽略 db.sql.gz 等敏感文件。

步骤 3：启动环境

ddev start

# 输出：
# Starting my-drupal-site...
# Network ddev-default created
# Creating ddev-my-drupal-site-db ... done
# Creating ddev-my-drupal-site-web ... done
# Creating ddev-my-drupal-site-dba ... done
# Successfully started my-drupal-site
# Project can be reached at https://my-drupal-site.ddev.site https://127.0.0.1:32772
# You can run 'ddev describe' to get more information

步骤 4：验证环境健康

# 查看服务状态
ddev describe

# 输出关键信息：
# NAME            STATUS    URLS
# my-drupal-site  Running   https://my-drupal-site.ddev.site
#                           https://127.0.0.1:32772

# 进入 Web 容器执行 Drush
ddev exec drush status

# 输出应包含：
#  Drupal version                  : 9.5.13
#  Site URI                        : https://my-drupal-site.ddev.site
#  Database driver                 : mysql
#  Database hostname               : db
#  Database port                   : 3306
#  Database username               : db
#  Database name                   : db
#  PHP configuration               : /etc/php/8.1/fpm/php.ini
#  PHP OS                          : Linux
#  Drush script                    : /var/www/html/vendor/drush/drush/drush
#  Drush version                   : 11.5.1

注意：如果 ddev exec drush status 报错 Command 'drush' not found ，说明 vendor/bin/drush 未生成。运行 ddev composer install 重新安装依赖。DDEV 的 composer 命令在容器内执行，确保使用正确的 PHP 版本。

4.3 安装 Drupal 9：浏览器安装与命令行安装双路径

浏览器安装（推荐新手）

1. 打开浏览器，访问 https://my-drupal-site.ddev.site ；
2. DDEV 会自动重定向到 https://my-drupal-site.ddev.site/install.php ；
3. 选择语言，点击“Save and continue”；
4. 数据库配置页面：
   • Database name: db
   • Database username: db
   • Database password: db
   • Database host: db （不是 localhost ！）
   • Database port: 3306
5. 点击“Save and continue”，等待安装完成；
6. 设置站点信息（站点名称、管理员邮箱、用户名、密码），完成安装。

命令行安装（推荐 CI/CD 或批量部署）

# 生成一次性安装命令（替换 YOUR_SITE_NAME, ADMIN_EMAIL, ADMIN_PASS）
ddev exec drush site:install standard \
  --site-name="My Drupal Site" \
  --account-name=admin \
  --account-pass=admin123 \
  --account-mail=admin@example.com \
  --locale=en \
  --yes

# 输出：
# Installation complete.  User name: admin  User password: admin123
# Congratulations, you installed Drupal!

提示：命令行安装后， ddev exec drush uli 可生成一次性登录链接（如 https://my-drupal-site.ddev.site/user/reset/1/1698765432/abc123def456ghi789jkl012mno345pqr678stu901vwx234yz567... ），点击即可免密登录，比记密码更安全。

4.4 日常开发操作：模块启用、主题切换、数据库同步

启用模块（以 Devel 模块为例）

# 1. 用 Composer 安装模块（自动处理依赖）
ddev composer require drupal/devel:^4.0

# 2. 启用模块（Drush 命令）
ddev exec drush en devel devel_generate -y

# 3. 清除缓存
ddev exec drush cr

切换主题（以 Olivero 主题为例）

# 1. 启用 Olivero（Drupal 9.4+ 默认主题）
ddev exec drush theme:enable olivero

# 2. 设为默认主题
ddev exec drush config:set system.theme default olivero

# 3. 清除缓存
ddev exec drush cr

数据库同步（从生产环境拉取最新数据）

# 1. 在生产环境导出数据库（假设生产环境也用 DDEV）
# ssh into production server, then:
ddev export-db --file=prod-db.sql.gz

# 2. 将 prod-db.sql.gz 复制到本地项目根目录
# 3. 导入到本地数据库
ddev import-db --src=prod-db.sql.gz

# 4. 更新文件（同步 sites/default/files）
ddev rsync --src=:/var/www/html/web/sites/default/files/ --dest=web/sites/default/files/

实操心得： ddev import-db 会自动解压 .sql.gz 并执行 mysql -u db -pdb db < file.sql 。它比手动 gunzip + mysql 更可靠，因为 DDEV 知道数据库容器名和凭据。文件同步用 ddev rsync 而非 rsync 命令，是因为它能正确处理 Docker 容器内的路径映射。

5. 常见问题与排查技巧实录：从启动失败到模块报错的实战手册

5.1 启动失败： ddev start 卡在 Starting services...

现象 ： ddev start 执行后，终端停在 Starting services... ，无报错，10 分钟后超时。

排查步骤 ：

1. 检查 Docker 是否运行 ：
   • Windows/macOS：确认 Docker Desktop 图标在任务栏/菜单栏，右键显示 “Docker Desktop is running”。
   • Linux： sudo systemctl status docker ，确认 active (running) 。
2. 检查端口占用 ：DDEV 默认用 80 和 443 端口。运行 lsof -i :80 （macOS/Linux）或 netstat -ano | findstr :80 （Windows），查看是否有其他程序（如 IIS、Apache）占用了端口。若有， ddev config --router-http-port=8080 --router-https-port=8443 修改端口。
3. 检查 WSL2 磁盘空间 （Windows）： wsl -l -v 确认 WSL2 分发版状态， wsl -d Ubuntu-22.04 进入后运行 df -h ，若 / 分区使用率 100%，需清理 ~/.docker 或运行 wsl --shutdown 后重启。

提示：我遇到过三次 ddev start 卡住，两次是 Docker Desktop 未启动（图标灰了），一次是 WSL2 磁盘满（ /var/lib/docker 占用 20GB）。记住 ddev poweroff 是万能重启键，它会停止所有 DDEV 容器，比 docker-compose down 更彻底。

5.2 访问白屏： https://my-drupal-site.ddev.site 显示空白页

现象 ：浏览器打开 URL，页面空白，无错误，Network 面板显示 200 OK 但 Response 为空。

排查步骤 ：

1. 检查 PHP 错误日志 ：

   ddev logs -s web
   # 查找 "PHP Fatal error" 或 "PHP Parse error"
   

2. 检查 Drupal 日志 ：

   ddev exec drush watchdog:show --limit=10
   # 或查看 web/sites/default/files/php://stderr
   

3. 典型原因与修复 ：
   • vendor/autoload.php not found ： composer install 未执行。运行 ddev composer install 。
   • settings.php not found ： web/sites/default/settings.php 权限错误。运行 ddev exec chmod 644 web/sites/default/settings.php 。
   • Trusted Host Settings 报错 ： settings.php 中 trusted_host_patterns 未匹配域名。DDEV 已自动注入，但如果你手动改过，运行 ddev exec drush ev "\$settings['trusted_host_patterns'] = ['^my\-drupal\-site\.ddev\.site\$'];" 重置。

注意：DDEV 的 web 容器日志默认级别是 notice ，要看到 warning 和 error ，需在 .ddev/config.yaml 中添加：

web_extra_exposed_ports: []
web_environment:
  - "PHP_ERROR_REPORTING=E_ALL & ~E_DEPRECATED & ~E_USER_DEPRECATED"

5.3 模块启用失败： drush en my_module 报 Class 'MyModule' not found

现象 ： ddev exec drush en my_module -y 后报错 `Error: Class