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 必须提交。
Drupal 9+ 项目里，Composer 不是“配合使用”的工具，而是唯一可信的依赖与自动加载控制中心——跳过它直接操作 web/modules/contrib/ 或 vendor/，不出三天就会遇到 Class not found、drush cr 失败、CI 构建漂移。
初始化项目必须用 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.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 流水线构建出的环境和本地不一致——你本地能跑，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 会导致每次请求都走 classmap 查找，性能明显下降。
关键约束：
-
composer.lock必须提交到 Git——它是生产环境依赖精确还原的唯一依据 -
vendor/和web/sites/default/settings.php必须进.gitignore，前者是生成物，后者含敏感配置 - Web 服务器 DocumentRoot 必须指向
web/，且composer.json、vendor/等目录不可被 HTTP 直接访问
最常被忽略的是 scaffold 文件同步：升级 drupal/core-recommended 后，web/index.php 或 web/.htaccess 没更新，首页白屏但 drush status 显示正常——问题就出在这里。
