Drupal 11 使用Composer & Drush 更新版本

Drupal 目前最新推荐的版本是 11.2.x 系列，同时 11.3.x 也已发布，带来了号称“十年最大性能提升”——查询量减少 62%，同等数据库负载下可多处理 26%–33% 的请求量，并原生集成了 HTMX。

无论你正在使用 Drupal 11 还是准备从 Drupal 10 升级到 11，使用 Composer 和 Drush 进行更新，都是官方推荐的标准方法。

本教程完整覆盖从准备工作到完成验证的全流程。

一、准备工作（必读）

1.1 环境要求确认

Drupal 11 对运行环境有明确的最低版本要求：

• PHP 8.2 或更高版本（官方推荐 PHP 8.3，11.3.0 已支持 PHP 8.5）
• Composer 2.4 或更高版本
• MySQL 8.0.17+ / MariaDB 10.4+ / PostgreSQL 12+
• Drush 13 或更高版本（Drupal 11 需要 Drush 13 以保持兼容性）

检查 Drush 版本的命令：

drush --version

若版本低于 13，请先更新 Drush。

1.2 完整备份

这是最重要的一步，切勿跳过。

# 备份代码（在项目根目录执行）
tar -czf backup_code_$(date +%Y%m%d_%H%M%S).tar.gz .

# 备份数据库（使用 Drush）
drush sql-dump --ordered-dump --gzip --result-file=db_backup_$(date +%Y%m%d_%H%M%S).sql.gz

备份完成后，建议先在本地或预发布环境中进行更新测试，确认无问题后再操作生产环境。

1.3 启用维护模式

在生产环境更新时，务必先将站点置于维护模式：

# 通过 Drush 快速设置
drush state:set system.maintenance_mode 1

# 恢复站点访问的命令（更新完成后执行）
# drush state:set system.maintenance_mode 0

1.4 检查模块兼容性（可选但强烈推荐）

使用 Upgrade Status 模块预先扫描站点，确认所有已安装模块和主题均已兼容 Drupal 11：

composer require 'drupal/upgrade_status:^4.0'
drush en upgrade_status -y

安装后，访问 /admin/reports/upgrade-status 查看详细报告，重点关注已启用模块的兼容性问题。

1.5 更新贡献模块至最新版本

将现有的所有贡献模块和主题更新到最新版本：

# 查看有可用更新的模块
composer outdated "drupal/*"

# 批量更新所有贡献模块
composer update drupal/* --with-dependencies

二、核心更新流程

2.1 理解版本约束

在进行更新之前，先打开 composer.json 文件，查看 drupal/core-recommended 的版本约束写法。

• 如果约束是 ^11（如 ^11.2），表示“允许安装符合规则的最新版本”，无需修改 composer.json 即可安装 11.2.x、11.3.x 等更新；
• 如果约束是 固定版本号（如 11.1.0），则需要手动提高版本约束。

对于采用语义版本约束（^）的项目，执行更新命令后 composer.json 不会改变，只有 composer.lock 会被更新，这完全正常。

2.2 更新 Drupal 核心

根据你需要更新的版本类型，选择对应的命令：

场景一：更新到最新的小版本（如 11.2.x → 11.3.x）

composer update drupal/core-recommended --with-dependencies

场景二：明确指定目标版本

# 更新到 11.3
composer require 'drupal/core-recommended:^11.3' -W

该命令会同时更新 composer.json 和 composer.lock，适合希望将版本约束明确写入文件的场景。

场景三：从 Drupal 10 升级到 Drupal 11

若当前为 Drupal 10，首先确保已更新至 Drupal 10.3 或更高版本，然后修改 composer.json 中的核心包版本约束，也可以直接执行：

composer require drupal/core-recommended:^11 drupal/core-composer-scaffold:^11 drupal/core-project-message:^11 --update-with-dependencies

2.3 执行数据库更新

代码更新完成后，需要让 Drupal 执行数据库更新脚本：

drush updatedb

系统会列出待执行的更新并提示确认。如需自动确认（在自动化脚本中使用），可添加 -y 参数：

drush updatedb -y

2.4 导入配置并清理缓存

如果项目中使用了配置管理（Configuration Management），导入最近的配置变更：

# 导入配置变更
drush config:import -y

# 清理缓存
drush cache:rebuild

2.5 使用 drush deploy 一键完成

对于 Drupal 10.3 及以上版本（包括 Drupal 11），Drush 提供了 deploy 命令，它将更新流程中的核心步骤串联为一条命令：

drush deploy -y

该命令按顺序自动执行：

1. drush updatedb（数据库更新）
2. drush config:import（配置导入）
3. drush cache:rebuild（缓存重建）
4. drush deploy:hook（自定义部署钩子）
5. drush cache:warm（Drupal 11.2+ 缓存预热）

在大多数场景下，执行 drush deploy -y 即可完成更新全过程。

三、完整更新流程速查表

以下为推荐的生产环境更新流程，建议按顺序逐条执行：

四、更新后验证

更新流程结束后，需要进行完整的验证：

1. 访问站点首页，确认页面正常加载；
2. 登录后台（/user/login），确认管理员功能正常；
3. 测试关键功能：内容创建/编辑、用户注册、搜索、菜单导航等核心流程；
4. 检查状态报告：/admin/reports/status，确认无报错；
5. 检查可用更新报告：/admin/reports/updates，确认 Drupal 核心版本信息正确。

五、常见问题与故障排查

Q1：更新后站点白屏或报错怎么办？

首先运行 drush cr 清理缓存。如果问题依旧，在 settings.php 中启用错误显示：

$config['system.logging']['error_level'] = 'verbose';

然后重新访问页面或执行 drush updatedb，查看完整错误信息。

Q2：Composer 提示依赖冲突如何解决？

先执行 composer update --dry-run 查看具体冲突信息。常见冲突来源于模块版本约束过紧。可尝试以下命令查看哪些模块存在版本约束问题：

composer why-not drupal/core-recommended ^11

Q3：更新过程中如何查看当前 Drupal 版本？

# 方法一：使用 Drush
drush core:status --field=drupal-version

# 方法二：使用 Composer
composer show drupal/core-recommended | grep versions

Q4：从 Drupal 10 升级到 11 之前，有哪些必须注意的检查项？

升级前需完成模块兼容性检查、确保站点运行在 Drupal 10.3+、备份数据库和代码文件，并在本地或预发布环境中完整测试后再应用于生产环境。

结语

使用 Composer 配合 Drush 来更新 Drupal 核心，是 Drupal 社区推荐的标准做法。Composer 负责代码层面的依赖管理，Drush 负责数据库更新和运维操作，两者配合可以高效、可靠地完成从准备工作到部署上线的整个更新流程。

掌握这套流程后，无论是日常的补丁更新还是小版本迭代，都能轻松应对。建议将这些步骤整理为部署脚本或纳入 CI/CD 流程，进一步提升自动化水平。