如何搭建简单、易维护且跨 OS 的 Drupal 本地开发环境？

建议优先采用 DDEV 加容器运行时，把 PHP、数据库、Composer 和 Drush 放进项目环境，并将环境配置提交到 Git。如果团队已经熟悉 Lando，或需要它的 Acquia 集成，也可以选择 Lando。

这样能减少项目对宿主机 PHP 和系统软件版本的依赖，让 macOS、Windows 和 Linux 使用同一套项目配置。现有的 Acquia Site Factory 和部署流程可以分阶段迁移，无须为了更换本地环境一次性全部重做。

为什么容器方案更适合这个问题？

目前需要维护的组件各自都在变化：宿主机系统、PHP、Vagrant、VirtualBox，以及虚拟机里的依赖和初始化脚本。任何一个组件更换版本，都可能影响其他环节。

DDEV 把项目所需的服务和版本写进配置，通过容器运行。日常开发时可以执行：

ddev composer install
ddev drush status

这些命令使用容器里的 PHP 和工具，宿主机无须另外安装一套项目专用 PHP。DDEV 支持 macOS、Windows 和 Linux，采用 Apache 2.0 许可证，可以免费使用。DDEV 官方介绍

容器的运行时、文件共享和网络配置仍需要维护，macOS、Windows 上运行 Linux 容器也仍涉及虚拟化。DDEV 能把这些配置集中起来，减少每个项目单独维护虚拟机的工作。

Dev Desktop、Cloud IDE 和其他方案怎么选？

Dev Desktop：安装方便，但已经停止支持

Dev Desktop 的图形化安装方式曾让入门更容易，但 Acquia Dev Desktop 2 已于 2021 年 6 月 30 日结束支持。课程中的推荐反映了当时的工具选择，不能直接作为现在的选型依据。Acquia 产品生命周期表

Cloud IDE：先确认现有订阅包含什么

Cloud IDE 在 Acquia 基础设施上运行，通过浏览器使用，并与 Acquia 平台集成。它能减少本机工具链的安装工作，适合设备受限，或希望集中管理开发环境的团队。Acquia 开发工具介绍

使用 Cloud IDE 会限制离线开发，编辑和调试体验也受网络状况影响。迁移前，应实际验证所需的扩展、服务和 Site Factory 多站点工作流。

是否需要额外付费，要看现有合同。Acquia 的订阅说明列出了不同套餐包含的 Cloud IDE 权益；你们已有 Site Factory 合同，应先核对可用数量、权限，以及增加环境的费用。Cloud IDE 并非面向所有人的免费服务。Acquia 订阅说明

Lando：值得与 DDEV 一起评估

Lando 提供 Acquia 插件，可以配置接近 Acquia 的本地服务，也提供数据拉取和相关命令行工具。团队如果已有 Lando 使用经验，继续采用它也很实际。Lando Acquia 插件文档

Acquia 集成能否覆盖你们的全部 Site Factory 操作，还需要验证。选型时应使用一个真实站点测试，只运行全新的 Drupal 示例不足以确认这一点。

Lightning 是否要求使用 Mac？

使用 Lightning 本身不能说明开发者必须使用 Mac。Lightning 是 Drupal 发行版，项目能否跨系统开发，还取决于自定义脚本、二进制依赖、路径写法和团队工具链。

如果某一步只能在 Mac 上运行，应找到对应的命令及其依赖。常见的处理方式是把脚本放进 Linux 容器，移除宿主机绝对路径，并避免依赖 macOS 专有命令。

Lightning 本身也需要单独安排维护：它已于 2021 年 11 月 2 日结束支持，Lightning 3、4、5 不再接收安全更新或错误修复。容器可以帮助复现旧环境，但无法恢复这些依赖的维护。Lightning 项目说明

如何把现有项目迁移到 DDEV？

1. 先记录项目实际需要的版本

从现有可运行环境和 Acquia 环境中确认：

• Drupal、PHP、Composer、Drush 的版本要求。
• 数据库类型及版本，以及需要的 PHP 扩展。
• 文档根目录，例如 docroot 或 web。
• Solr、Memcached 等额外服务。
• Site Factory 的站点目录、域名映射和设置加载方式。

把这些信息写进项目文档和环境配置。不要直接采用工具默认值，也不要在更换环境时顺便升级所有依赖。

2. 安装 DDEV 和容器运行时

可以采用以下免费组合：

具体安装方式和系统要求，以 DDEV 安装文档及容器运行时说明为准。

容器运行时的许可需要单独核对。DDEV 可以免费使用，Docker Desktop 则对部分商业使用场景要求付费订阅，团队选用前应确认是否适用。Docker Desktop 许可说明

Windows 使用 WSL2 时，建议把项目放在 WSL 的 Linux 文件系统中，并在 WSL 终端执行项目命令，避免混用 Windows 与 Linux 两套路径和工具。

3. 在已有仓库里生成项目配置

克隆项目后，在仓库根目录运行：

ddev config

按提示选择项目实际使用的文档根目录和 Drupal 项目类型。随后检查 .ddev/config.yaml，设置与项目兼容的 PHP 和数据库版本，再启动环境：

ddev start
ddev composer install

配置完成后，将可共享的 DDEV 配置提交到 Git。其他成员通常只需启动环境，无须重复选择项目参数。DDEV Drupal 快速入门

Acquia 项目还要检查 settings.php 的加载顺序。DDEV 通常会生成 settings.ddev.php 并添加引用，现有的 Acquia 设置或自定义逻辑可能需要相应调整。应确认本地数据库配置已生效，并避免在本地无条件加载仅存在于 Acquia 服务器上的文件。DDEV 设置管理说明

4. 导入数据库和上传文件

已有站点应导入与当前代码匹配的数据库备份。执行前，请将下面的文件路径替换为实际路径；导入会覆盖目标本地数据库：

ddev import-db --file=../backups/site.sql.gz
ddev drush status
ddev drush cr
ddev launch

上传文件需要另外恢复到项目实际使用的文件目录。首页能打开后，还应检查登录、图片、搜索和缓存服务。

这组命令适用于单个本地站点。Site Factory 多站点项目需要分别处理站点目录、域名映射和数据库；Drush 命令通常也要通过 --uri 指向目标站点，不能默认所有操作都针对 sites/default。

Composer 和 BLT 怎样处理才更稳定？

已有项目应提交 composer.lock，新成员安装环境时执行 composer install。composer update 会重新解析依赖，应留给有计划的升级，不宜用来试着修复环境问题。Composer 基本用法

排查问题时，先确认实际运行环境：

ddev exec php -v
ddev composer --version
ddev composer validate
ddev composer check-platform-reqs

check-platform-reqs 会检查实际运行的 PHP 和扩展是否满足已安装依赖的要求。如果报错发生在 Composer scripts 或插件阶段，还应检查它调用的 BLT、自定义脚本和外部程序。Composer 命令说明

Acquia 已于 2024 年 12 月 31 日结束支持 BLT，并明确表示不会为其增加 Drupal 11 支持，因此 BLT 也需要安排迁移。BLT 生命周期说明

可以分两步进行：

1. 先在新容器环境里复现现有构建和 artifact 产出，确保部署结果可以验证。
2. 再逐项迁移 BLT 承担的依赖安装、检查、配置处理和 artifact 构建任务，并考虑放入 CI。

从电脑上移除 BLT 前，应先弄清它实际执行了哪些任务。否则，本地站点虽然能运行，部署产物仍可能缺少文件或构建步骤。

怎样让环境长期容易维护？

Drupal 本地开发没有强制要求所有项目使用同一种工具。团队可以统一以下约定：

• 环境配置和依赖锁文件进入 Git，版本调整通过代码审查。
• PHP、Composer、Drush 和构建命令统一在容器内运行。
• 数据库、上传文件与代码分别管理，备份和凭据不进入仓库。
• 初始化流程可重复执行，避免每次启动都重新下载数据库或完整重建项目。
• 在目标操作系统上验证完整流程，包括依赖安装、数据库导入和 artifact 构建。

跨系统开发还要留意文件名大小写、脚本换行符和 ARM64 镜像支持。容器能减少系统差异，硬编码路径和仅支持某种架构的程序仍需项目自己处理。

对当前这套 Acquia Site Factory 项目，建议先选一个有代表性的站点试迁 DDEV。保留原部署流程，验证 Windows、macOS、Linux 上的构建结果后，再推广给团队。

备注：内容仅供参考。