Composer如何配合Drupal使用_Composer Drupal项目集成方式【详解】

Drupal 9+ 项目中 Composer 是唯一可信的依赖与自动加载控制中心

在 Drupal 9+ 的项目里，有一个认知必须扭转：Composer 不再是那个可以“配合使用”的辅助工具，它已经成为了整个项目依赖与自动加载机制唯一可信的控制中心。 如果还抱着老习惯，跳过它直接去操作 web/modules/contrib/ 或者 vendor/ 目录，不出三天，各种诡异问题就会找上门来——Class not found 错误、drush cr 执行失败、CI 构建环境与本地环境漂移，这些几乎都是由此引发的连锁反应。

Drupal 9+ 项目中 Composer 是唯一可信的依赖与自动加载控制中心，跳过它直接操作 web/modules/contrib/ 或 vendor/ 必导致 Class not found、drush cr 失败、CI 构建漂移；必须用 composer create-project drupal/recommended-project 初始化，严禁手动下载核心或模块，所有安装、启用、卸载、升级均须遵循 composer require → drush en、composer remove → drush pm:uninstall 流程，生产部署仅允许 composer install --no-dev --optimize-autoloader 且 composer.lock 必须提交。

初始化项目必须用 composer create-project drupal/recommended-project

这可不是什么“推荐的最佳实践”，而是为了避免项目目录结构从一开始就陷入混乱的硬性起点。尝试手动下载 tar 包、git clone 核心仓库，或者在一个空目录里直接运行 composer require drupal/core，这些操作都会导致关键文件缺失，比如 web/ 目录下没有 index.php 或 .htaccess，或者 vendor/autoload.php 无法正确映射到 Drupal 的 PSR-4 命名空间。

具体操作时，有几个要点需要牢记：

• 务必在一个空目录中执行命令，例如：composer create-project drupal/recommended-project my-site
• 命令执行后，立刻检查几个关键位置：my-site/web/index.php 是否存在？my-site/composer.json 中依赖项是否为 "drupal/core-recommended": "^10.2"（而不是简单的 "drupal/core": "*"）？
• 如果过程中提示 zlib_decode(): data error 这类错误，别慌，先运行 composer clear-cache 清理缓存，然后重试即可。

composer require drupal/foo 装不上？先查三处硬卡点

当报错信息里出现类似 Conclusion: don‘t install drupal/foo x.x 的提示时，问题通常不在于命令本身写错了，而是版本被锁死或者执行上下文有误。

排查时，建议按这个顺序来：

• 首先，确认当前目录是不是项目的根目录（即包含 composer.json 和 vendor/ 的那个目录）。如果误入了 web/ 或 modules/ 这样的子目录，命令自然会失败。
• 其次，检查 composer.json 文件，看看 "drupal/core" 的版本是否被锁死在较低版本（比如 "^9.5"），而你想要安装的模块（例如 drupal/config_ignore）却要求更高的核心版本（比如 ^10.0）。
• 最后，在没有运行 composer why-not drupal/core:10.1.0 这类命令来诊断依赖冲突之前，切忌直接删除 composer.lock 或强行修改版本号——这相当于主动放弃了构建的可重现性。

举个例子，假设想安装 drupal/devel 模块却失败了。正确的做法是，先运行 composer show drupal/core-recommended 确认当前 Drupal 核心的确切版本，然后去 drupal.org 上查看该模块页面的兼容性说明，确保版本对齐后，再执行类似 composer require drupal/devel:^5.1 的命令。

模块启用 ≠ 模块安装，drush pm:enable 不能替代 composer require

这里有个关键概念需要厘清：drush pm:enable 命令仅仅是在数据库层面切换模块的启用状态，它不会下载代码文件，不会向自动加载器注册命名空间，也不会校验模块的依赖关系。如果你手动把模块文件扔进 web/modules/contrib/ 目录，Composer 对整个事件是完全不知情的。

这么做的后果非常直接：

• 下一次执行 composer update 时，你手动放进去的模块文件很可能会被无情地删除。
• 运行 drush cr 时可能会报错，例如 Class ‘Drupal\devel\DevelController‘ not found，原因就在于 vendor/autoload.php 根本没有加载该模块对应的命名空间。
• CI/CD 流水线构建出的生产环境会与你的本地环境不一致，导致“在我机器上能跑，在 CI 上就报错”的经典问题。

因此，务必遵循正确的流程：安装模块时，先 composer require drupal/pathauto，再 drush en pathauto；卸载时则反过来，先 drush pm:uninstall pathauto，再 composer remove drupal/pathauto。

生产部署只允许 composer install --no-dev --optimize-autoloader

在开发环境中，直接运行 composer install 没什么问题。但到了生产服务器上，如果漏掉了 --no-dev 这个参数，就会把 phpunit、behat 等一大堆开发依赖也打包进去，这不仅会无谓地增大部署体积、拖慢自动加载速度，还可能暴露测试入口，带来安全风险。同样，如果漏掉 --optimize-autoloader，会导致每次处理请求时，PHP 都需要进行 classmap 查找，对性能的影响是显而易见的。

关于生产部署，还有几个关键约束必须遵守：

• composer.lock 文件必须提交到 Git 仓库。它是确保生产环境能精确还原所有依赖版本、实现可重复构建的唯一依据。
• vendor/ 目录和 web/sites/default/settings.php 文件必须列入 .gitignore。前者是构建生成的产物，后者通常包含数据库密码等敏感配置。
• Web 服务器（如 Apache 或 Nginx）的 DocumentRoot 必须指向 web/ 目录，并且要确保 composer.json、vendor/ 等上层目录不能被 HTTP 直接访问。

最后，一个最容易被忽略的细节是关于 scaffold 文件的同步。当你升级了 drupal/core-recommended 后，如果 web/index.php 或 web/.htaccess 这类由 Drupal 脚手架管理的文件没有同步更新，就可能出现首页白屏，但 drush status 命令却显示一切正常的诡异情况——问题的根源往往就在这里。