DDEV 配合Drupal：搭建本地开发、导入站点与导出项目

作者：成都长风云Drupal开发团队
摘要：借助DDEV搭建可靠的Drupal本地开发环境。按照本文步骤，你可以创建全新站点、导入已有项目，还能导出代码、数据库与上传文件，用于在其他环境复现项目。

DDEV能为Drupal项目做什么
开始前：理解需要迁移的项目组成部分
步骤1：安装DDEV与Docker运行环境
步骤2：新建Drupal 11项目
步骤3：从其他环境收集已有项目资源
步骤4：将代码接入DDEV
步骤5：导入数据库前检查本地配置
步骤6：导入数据库与上传文件
步骤7：验证导入完成的网站
步骤8：导出本地数据库
步骤9：导出上传文件与配置项
步骤10：导出代码与环境定义文件
步骤11：将导出包恢复到另一个DDEV项目
项目导出不等同于项目部署
常见问题排查
日常高频DDEV命令速查

想要本地运行Drupal站点，不该耗费大量时间折腾PHP版本、数据库配置、以及昨天还运行正常的Web服务器。

DDEV为每一个项目提供可配置的开发环境。你使用熟悉命令操作，DDEV则负责管理运行应用与数据库的容器。

不管是新建Drupal站点、接手已有项目，还是把工作交付给其他开发者，DDEV都非常适用。本文覆盖这三类场景，同时提醒一个容易忽略的关键点：Drupal项目不只是代码文件夹。

DDEV能为Drupal项目做什么

DDEV使用容器提供应用运行所需的各类服务。项目配置存放在.ddev目录，团队可以把环境配置和代码一起提交共享。

你可以直接在该环境内部运行PHP工具：

ddev composer install
ddev drush status

这就避免团队中不同开发者使用Composer时，PHP版本不一致的问题。

项目文件依旧可以在本机编辑器直接打开编辑；数据库存放在容器管理的数据卷中，因此仅复制代码文件夹，并不会同步数据库。

DDEV只负责提供本地运行环境。项目可能还需要额外服务，例如搜索引擎、Redis缓存或者前端构建流程。

开始前：理解需要迁移的项目组成部分

标准Drupal站点包含如下组件：

组件	包含内容	常用迁移方式
代码	自定义模块、主题、Composer配置文件、脚本	Git仓库或审核后的源码压缩包
数据库	内容、用户、生效配置、业务数据	SQL导出备份
上传文件	图片、文档以及其他媒体资源	文件压缩包或合规文件传输工具
环境配置	DDEV配置、本地覆盖配置、服务连接信息	共享配置文件 + 独立保管密钥秘钥

Drupal配置导出是工作流中另一重要部分，它记录字段、内容类型、视图等设置。配置导出不能替代包含内容与用户数据的数据库备份。

本文示例基于Composer管理的Drupal项目，文档根目录为web。所有项目命令需要在包含composer.json的目录执行。

命令适用于macOS、Linux、Windows WSL2终端。示例路径与仓库地址请替换为你自己项目实际值。

步骤1：安装DDEV与Docker运行环境

DDEV依赖受支持的Docker运行环境，安装方式取决于你的操作系统。

macOS

brew install ddev/ddev/ddev
mkcert -install

证书安装可以让浏览器信任本地HTTPS站点。

Windows

参考DDEV官方Windows安装文档。推荐使用WSL2方案，在Linux环境内部署Docker CE。

使用该方案时，命令要在WSL2内部执行，项目文件存放在WSL的Linux文件系统，例如~/projects，不要放在/mnt/c路径。

Linux

参考对应发行版的Docker与包管理器官方文档。Debian系和RPM系仓库配置不一样。

务必使用官方安装指引，不要混用网上不同教程的安装步骤。

安装完成校验：

docker version
ddev version

如果Docker提示无法连接服务，请先解决该问题再创建项目。

步骤2：新建Drupal 11项目

本节用于全新空站点；如果你要导入已有网站，请直接跳转到步骤3。

mkdir -p ~/projects/drupal-local
cd ~/projects/drupal-local

ddev config \
 --project-type=drupal11 \
 --docroot=web \
 --php-version=8.3 \
 --database=mariadb:10.11

ddev start

上面PHP与数据库版本仅为示例。团队项目请选择与项目要求匹配的受支持版本。DDEV会把配置保存到.ddev/config.yaml。

下载Drupal并安装Drush：

ddev composer create-project "drupal/recommended-project:^11"
ddev composer require drush/drush

安装新站点：

ddev drush site:install standard \
 --account-name=admin \
 --site-name="Drupal Local" \
 -y

ddev drush user:login
ddev launch

复制Drush输出的一次性登录链接访问本地后台，该链接等同登录凭证。

千万不要对需要保留数据的已有站点执行site:install；该命令会初始化全新数据库，它不是数据导入命令。

步骤3：从其他环境收集已有项目资源

要把托管平台、其他开发者或者其他本地工具中的站点迁移过来，你需要准备：

正确版本的代码，包含composer.json与composer.lock
数据库备份文件，通常为database.sql.gz
公开上传文件，来源一般是web/sites/default/files
项目需要的私有文件或者外部存储资源
项目对应的PHP版本、数据库引擎版本、额外依赖服务要求

数据库备份和代码版本必须互相匹配。数据库与文件可以使用托管平台备份工具或者团队导出流程获取。网站代码压缩包一般不包含数据库。

数据库备份与资源压缩包请存放在网站文档根目录之外。

如果原始数据包含客户隐私，优先使用脱敏数据集。在导入项目前，提前准备本地凭据或者关闭第三方集成。

步骤4：将代码接入DDEV

基于Git的项目，示例如下（替换仓库地址）：

mkdir -p ~/projects

git clone \
 [https://example.com/your-team/your-drupal-project.git](https://example.com/your-team/your-drupal-project.git) \
 ~/projects/drupal-existing

cd ~/projects/drupal-existing

切换到和数据库备份相对应的分支或提交版本。如果你拿到的是代码压缩包，解压到项目目录，确认目录下存在composer.json。

如果目录已经存在.ddev/config.yaml，直接审阅复用；启动环境前查看项目说明与钩子配置。

项目没有DDEV配置则手动创建。以Drupal11，PHP8.3，MariaDB10.11举例：

ddev config \
 --project-name=drupal-existing \
 --project-type=drupal11 \
 --docroot=web \
 --php-version=8.3 \
 --database=mariadb:10.11

Drupal10项目请设置为drupal10；数据库引擎版本要和源环境对齐，MySQL与MariaDB不能直接视为完全兼容互换。

启动环境，安装锁定版本依赖：

ddev start
ddev composer install
ddev restart

使用composer install还原composer.lock记录的依赖版本；不要执行composer update，否则会升级依赖，破坏复现原有站点的目的。

步骤5：导入数据库前检查本地配置

DDEV会自动生成settings.ddev.php，并且在settings.php中添加引入代码。

请确认本地配置加载正常，如果原项目存在自定义配置逻辑、引用托管平台专属文件，尤其需要重点检查。

DDEV默认数据库连接参数：

数据库主机	`db`
数据库名	`db`
用户名	`db`
密码	`db`

交由DDEV维护本地数据库连接配置，不要把生产环境数据库凭据放到本地。本地专属覆盖配置和生产共享配置要分开。生成的settings.ddev.php默认是Git忽略文件。

项目如果依赖Redis、Solr等服务，请配置本地对应服务或者项目文档说明的本地降级方案。DDEV可以通过附加组件扩展服务能力。

步骤6：导入数据库与上传文件

从资源目录导入数据库：

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

该命令默认会完全覆盖本地现有数据库；执行前请导出需要保留的本地数据。

导入公开上传文件：

ddev import-files --source=/path/to/files.tar.gz

也可以直接从本地目录导入：

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

传入的路径是files目录本身，而不是整个Drupal代码根目录。

如果压缩包外层多一层files文件夹，需要指定解压路径，避免生成嵌套目录sites/default/files/files：

ddev import-files \
  --source=/path/to/files.tar.gz \
 --extract-path=files

导入前确认目标目录内容；DDEV导入前会清空目标目录，导入是覆盖替换，不是合并增量文件。私有文件、对象存储资源需要单独处理；公开文件导入成功不等于全部资源迁移完成。

步骤7：验证导入完成的网站

本地配置与第三方服务就绪之后执行：

ddev drush cache:rebuild
ddev drush status
ddev drush user:login
ddev launch

不能只看首页，需要做多项校验：

登录进入后台管理界面
浏览多条内容页面
检查图片与下载附件
新建、编辑测试内容
测试表单提交
验证搜索、自定义业务功能
查看Drupal状态报告与系统日志

如果检出的代码要求执行数据库更新，请先备份本地数据库，再按照项目流程执行。不要仅仅因为迁移站点就随意执行数据库更新或者导入配置。

本地邮件测试打开Mailpit：

ddev mailpit

DDEV可以捕获PHP邮件；直接调用SMTP或外部邮件接口会绕过捕获。表单、通知测试前确认邮件配置。支付接口、Webhook、CRM等第三方集成要切换成本地或沙箱环境。

步骤8：导出本地数据库

在网站根目录之外创建交付文件夹：

mkdir -p ../drupal-handoff

ddev export-db \
  --file=../drupal-handoff/database.sql.gz

该命令生成压缩SQL备份，只包含数据库数据，不含代码与上传文件。

做本地临时快照（做实验前快速备份）：

ddev snapshot --name=before-changes

快照适合本机回滚恢复；跨环境交接项目优先使用SQL导出，快照受数据库版本限制。两者都不等于完整项目备份。

步骤9：导出上传文件与配置项

项目根目录执行，打包公开上传文件：

tar -czf ../drupal-handoff/files.tar.gz \
  -C web/sites/default/files .

-C切换工作目录，末尾点号代表打包该目录下全部内容，输出格式适配ddev import-files导入。

项目如有私有文件，单独打包私有目录，恢复时存放于web根目录之外。

如果你做了Drupal配置变更，导出配置：

ddev drush config:export -y

使用项目已有的config‑sync目录。新项目没有配置同步目录时，先在web根目录外建立目录再使用配置导出工作流。提交前仔细审阅导出变更；本地开发模块、本地专属服务配置不要混入生产配置。

步骤10：导出代码与环境定义文件

团队交接优先共享Git仓库以及和数据库备份一一对应的精确提交版本。交付包中包含非敏感内容：

composer.json、composer.lock
自定义模块、主题以及业务代码
Drupal配置导出文件
.ddev/config.yaml以及需要共享的DDEV相关文件
前端构建清单与锁文件
说明文档README，描述项目依赖服务

先提交需要交付的文件。如需源码压缩包，从已提交的版本生成：

git archive \
  --format=tar.gz \
  --output=../drupal-handoff/code.tar.gz \
 HEAD

该命令只会打包已经git提交的文件，未提交修改、git忽略文件、未跟踪资源不会被打包；Git子模块需要额外处理。

完整交付目录结构示例：

drupal-handoff/
├── code.tar.gz
├── database.sql.gz
├── files.tar.gz
└── README.md

私有文件压缩包与其他资源另外存放。文档写明代码提交版本、PHP、数据库版本、依赖服务、资源路径；账号密钥通过团队专用密钥管理工具分发。

步骤11：将导出包恢复到另一个DDEV项目

验证导出包最有效的方式就是用它重建完整站点。新建独立目录：

mkdir -p ~/projects/drupal-restored

tar -xzf /path/to/drupal-handoff/code.tar.gz \
  -C ~/projects/drupal-restored

cd ~/projects/drupal-restored

如果压缩包已经包含DDEV配置，修改项目名称避免冲突：

ddev config --project-name=drupal-restored

ddev start
ddev composer install
ddev restart

导入数据库与文件：

ddev import-db \
  --file=/path/to/drupal-handoff/database.sql.gz

ddev import-files \
  --source=/path/to/drupal-handoff/files.tar.gz

ddev drush cache:rebuild
ddev drush status
ddev launch

按照README恢复私有文件和额外服务。压缩包不带DDEV配置的话，手动指定项目类型、文档根目录、PHP版本、数据库参数。完成后复现步骤7全部校验项。自定义代码缺失、压缩包目录层级错误、服务文档缺失，在本机复现阶段发现远比交付给别人之后再修复简单。

项目导出不等同于项目部署

导出包用于在某个时间点完整复现站点。生产部署则是迭代推送审核后的代码与配置，同时保留线上正在新增的内容、用户、订单、编辑数据。

千万不要直接把本地数据库覆盖到正在运行的生产数据库，这会覆盖线上新增业务数据。使用托管平台官方部署流程和团队发布计划。DDEV本地环境不提供生产密钥、DNS、备份、运维监控。本地用来测试版本，上线部署是独立受控流程。

常见问题排查

现象	优先检查项
DDEV无法启动	Docker是否正常运行；查看`ddev logs`日志
Drupal文件存在，浏览器报错	核对docroot文档根目录；确认composer依赖安装完成
数据库连接失败	确认DDEV生成配置加载；屏蔽托管平台专属数据库配置
Composer报PHP版本不匹配	DDEV内PHP版本和项目要求保持一致
图片资源缺失	检查文件导入路径，压缩包是否存在嵌套文件夹
站点跳转到生产域名	检查本地覆盖配置、域名模块、重定向规则、自定义代码
导入数据库出现排序规则报错	源数据库和目标数据库版本、字符集兼容性
本地表单发出真实邮件	检查SMTP、第三方邮件API，确认Mailpit拦截生效
恢复后项目功能不全	检查未提交文件、私有资源、git子模块、外部依赖服务

排错时不要同时修改PHP、数据库引擎、依赖包、Drupal配置；先完整还原原始环境，再做可控的变更调试。

日常高频DDEV命令速查

任务	命令
启动当前项目	`ddev start`
停止当前项目	`ddev stop`
列出本机全部DDEV项目	`ddev list`
查看项目访问地址与连接信息	`ddev describe`
打开网站	`ddev launch`
进入容器Shell终端	`ddev ssh`
重建Drupal缓存	`ddev drush cr`
查看Drupal运行状态	`ddev drush status`
打开邮件捕获面板Mailpit	`ddev mailpit`

开发结束执行ddev stop，数据库数据会保留。ddev stop不等于删除项目；删除DDEV项目操作会连带清除数据库。

一套好用的本地环境应当具备可复现性：其他开发者拿到代码包，导入数据与文件，参照README，就可以得到一模一样可运行站点。

搭建Drupal本地环境，最耗费时间的往往是依赖安装、数据库导入、缺失资源、复现托管平台环境。欢迎分享你的经验。