drupal-contrib-mgmt

Drupal 扩展模块管理

核心更新命令

composer require drupal/module_name --with-all-dependencies
composer require drupal/module_name:^3.0 --with-all-dependencies
drush updb -y && drush cr

检查 Drupal 11 兼容性

最快的方法——检查 .info.yml：

cat docroot/modules/contrib/MODULE_NAME/MODULE_NAME.info.yml | grep core_version_requirement

core_version_requirement: ^9.5 || ^10 || ^11   # D11 compatible
core_version_requirement: ^9 || ^10              # Not D11 compatible

• upgrade_status 警告 ≠ 不兼容——模块仍可能声明支持 ^11
• “Check manually”（手动检查）状态通常是误报（运行时版本检查）

Drupal 宽松插件

对于尚未更新版本要求的模块：

{
  "require": { "mglaman/composer-drupal-lenient": "^1.0" },
  "config": { "allow-plugins": { "mglaman/composer-drupal-lenient": true } },
  "extra": {
    "drupal-lenient": { "allowed-list": ["drupal/module_name"] }
  }
}

补丁管理（cweagans/composer-patches）

重要：使用 2.x——使用 git apply（可靠）。1.x 版本使用 patch 二进制文件（不稳定）。

{
  "require": { "cweagans/composer-patches": "^2.0" },
  "config": { "allow-plugins": { "cweagans/composer-patches": true } },
  "extra": {
    "composer-exit-on-patch-failure": true,
    "patches": {
      "drupal/module_name": {
        "Description of patch - Issue #3552531": "patches/module-fix-3552531-2.patch"
      }
    }
  }
}

2.x 注意事项：基于哈希的缓存——重新安装后补丁可能会悄然消失。

验证补丁是否已应用

./scripts/verify-patches.sh        # Check all critical patches
./scripts/verify-patches.sh --fix  # Auto-reinstall affected modules

将新补丁添加到验证中——编辑 scripts/verify-patches.sh：

CRITICAL_PATCHES=(
  "docroot/modules/contrib/MODULE:src/File.php:patternToFind:Description"
)

补丁丢失时：

1. 运行 ./scripts/verify-patches.sh 以确定问题
2. 运行 composer reinstall drupal/module_name 或 ./scripts/verify-patches.sh --fix
3. 如果仍然失败：运行 composer update --lock

查找补丁——创建之前先搜索

关键：编写自定义补丁前，务必先搜索 drupal.org 问题队列。

1. 提取准确的错误字符串：例如 "Unsupported operand types: array + null"
2. 搜索：https://www.drupal.org/project/drupal/issues?text=Unsupported+operand+types+array+null
3. 查找带有 .patch 附件的 RTBC（社区已审查并测试）问题
4. 下载到 patches/ 并添加到 composer.json

补丁命名：module-issue-NODEID-COMMENT.patch（例如：audiofield-d11-3432063-12.patch）

现有补丁在更新后失效时：

• 从文件名中提取节点 ID → 访问 drupal.org/node/NODEID → 在最新评论中查找更新后的补丁

创建本地补丁

务必从扩展仓库的单独克隆副本创建补丁，而不是从已安装的 vendor 副本创建。

cd ~/Sites && git clone [email protected]:project/module_name.git module_name-contrib
cd module_name-contrib && git checkout 1.0.3   # match installed version
# make changes...
git diff > ~/Sites/your-project/patches/module_name-custom-fix.patch

然后将其添加到 composer.json 并运行 composer reinstall drupal/module_name。

应用补丁

composer install                       # Install with patches
composer reinstall drupal/module_name  # Re-patch a single module
composer patches-repatch               # Re-patch all patched deps

Drupal 11 弃用项速查

弃用项	替代方案
REQUEST_TIME	\Drupal::time()->getRequestTime()
user_roles()	\Drupal\user\Entity\Role::loadMultiple()
file_validate_extensions()	file.validator 服务
_drupal_flush_css_js()	AssetQueryStringInterface::reset()

Upgrade Status 扫描

drush upgrade_status:analyze --all
drush upgrade_status:analyze module1 module2
drush upgrade_status:analyze --all --ignore-contrib   # custom code only

故障排除

错误	解决方案
Cannot apply patch	模块版本已变更——在 drupal.org/node/NODEID 查找更新后的补丁
requires drupal/core ^9	将其添加到 drupal-lenient 允许列表
patch has already been applied	补丁已合并到上游——从 composer.json 中移除
drush updb fails	尝试卸载 → 更新 → 重新启用模块