如何使用Composer来管理一个基于Drupal的项目？ (drupal-scaffold)

drupal-scaffold 是 Drupal 官方 Composer 插件，自动将核心骨架文件（如 .htaccess、robots.txt）从 drupal/core 复制到 web/ 目录；它内置于 composer create-project 流程，通过 post-create-project-cmd 脚本执行，依赖 scaffold.yml 配置，需手动运行脚本或更新 drupal/core 才触发。

什么是 drupal-scaffold，它和 composer create-project 有什么关系？

drupal-scaffold 是 Drupal 官方提供的一个 Composer 插件，负责把核心文件（比如 .htaccess、robots.txt、index.php）从 drupal/core 包里“复制”到项目根目录。它不是独立工具，而是嵌入在 composer create-project 流程中的自动行为。

当你运行 composer create-project drupal/recommended-project mysite，背后实际触发了 drupal-scaffold 的 post-create-project-cmd 脚本——这个脚本读取 drupal/core 里的 scaffold.yml，再按规则把文件写到你项目的正确位置。

• 不手动启用它，也默认生效；禁用需在 composer.json 中设 "enable-patching": false
• 它只管“骨架文件”，不处理模块、主题或配置的安装
• 若你用 composer install 而非 create-project，drupal-scaffold 不会自动运行（除非你手动加 composer run-script drupal-scaffold）

如何自定义 scaffold 文件（如改 robots.txt 或 .htaccess）？

直接修改根目录下的 robots.txt 或 .htaccess 没用——下次 composer update drupal/core 时会被覆盖。正确做法是：在项目根目录放一个 web/robots.txt（或对应路径），然后通过 scaffold.yml 告诉插件“跳过复制，用我的”。

例如，在项目根目录新建 scaffold.yml：

core:
  skip: true
files:
  'web/robots.txt': 'my-robots.txt'
  'web/.htaccess': 'my-htaccess'

再把你的定制文件 my-robots.txt 放在项目根目录下。这样 drupal-scaffold 就会跳过默认 robots.txt，改用你指定的路径。

• 所有路径都相对于项目根目录，不是 web/ 目录
• 若想完全禁用某文件复制，设 'web/robots.txt': false
• 修改 scaffold.yml 后，需手动运行 composer run-script drupal-scaffold 生效

为什么 vendor/drupal/core 更新后 web/index.php 没变？

这是常见误解：drupal-scaffold 只在特定时机运行：创建项目（create-project）、更新核心（update drupal/core）、或显式调用 drupal-scaffold 脚本。单纯 composer update 全局包，不会触发它——因为 drupal/core 没被列为更新目标。

Deep Search

智能文献、网页检索与分析工具。AI赋能，洞悉万象，让知识检索与总结触手可及

下载

验证方法：运行 composer show drupal/core 看当前版本，再执行：

composer update drupal/core --with-dependencies

这时 drupal-scaffold 才会重新生成 web/index.php 等文件。

• 若仍没更新，检查 composer.json 中是否误删了 "drupal/core-composer-scaffold" 依赖
• 运行 composer run-script --list 可确认 drupal-scaffold 脚本是否存在
• 注意：某些旧版 drupal/core（如 9.3.x 之前）用的是 drupal/core-composer-scaffold v2，v3 才支持 scaffold.yml 覆盖

使用 drupal-recommended-project 时，web/ 目录结构怎么组织才安全？

官方推荐模板（drupal/recommended-project）强制使用 web/ 为文档根目录，所有 Drupal 核心文件都放在 web/ 下。关键点在于：不能把 composer.json 放进 web/，也不能把 vendor/ 暴露在 Web 可访问路径下。

标准结构必须是：

mysite/
├── composer.json
├── web/
│   ├── index.php
│   ├── core/
│   └── sites/
├── vendor/
└── ...

• Web 服务器 DocumentRoot 必须指向 web/，不是项目根目录
• composer install 必须在项目根目录运行，否则 drupal-scaffold 找不到 scaffold.yml
• 模块应装在 web/modules/contrib/，主题在 web/themes/contrib/ ——这些路径由 Drupal 自动识别，不要改 composer.json 的 installer-paths

最易忽略的一点：如果你用的是 Acquia 或 Platform.sh，它们的部署流程可能绕过本地 composer install，此时要确保 CI 配置里显式调用了 drupal-scaffold，否则上线后 .htaccess 缺失会导致 404。