Drupal 11 使用Composer & Drush 更新最新版本

由 cc , 1 六月 2026

Drupal 目前最新推荐版本为 11.2.x 系列，11.3.x 版本已正式发布，带来十年最大性能优化：数据库查询量减少 62%，同等负载下可提升 26%–33% 请求处理能力，同时原生集成 HTMX 能力。

无论存量 Drupal 11 站点迭代更新，还是从 Drupal 10 跨版本升级至 11，官方标准方案均为 Composer 管理代码依赖 + Drush 执行站点运维。本教程适配 Drupal 多站点架构，完整覆盖环境准备、配置部署、版本更新、故障排查全流程，适配纯 HTML 文章/页面站点。

一、更新前置准备（必读，生产环境必执行）

1.1 环境兼容性校验（Drupal 11 硬性要求）

Drupal 11 对运行环境有明确最低版本限制，升级前务必核对：

PHP：8.2 及以上，官方推荐 8.3/8.5（11.3.x 完美兼容 PHP8.5）
Composer：2.4 及以上版本
数据库：MySQL 8.0.17+ / MariaDB 10.4+ / PostgreSQL 12+
Drush：13.0 及以上（Drupal11 专属兼容版本，低版本会出现命令失效、配置读取异常）

1.1.1 容器全局 Drush 环境部署（适配多站点）

针对容器化部署的 Drupal 多站点架构，配置全局可用、适配多站点的 Drush 启动脚本，彻底解决路径识别异常问题。

1. 生成健壮版 drush-wrap 启动脚本

mkdir -p /var/www/Drupal_Core/drush
cat > /var/www/Drupal_Core/drush/drush-wrap <<'EOF'
#!/bin/bash
# Drupal 项目根目录
PROJECT_ROOT="/var/www/Drupal_Core"
# Drush 绝对路径
DRUSH_BIN="${PROJECT_ROOT}/vendor/drush/drush/drush"

# 校验项目目录
if [ ! -d "${PROJECT_ROOT}" ]; then
    echo "ERROR: 项目目录不存在 ${PROJECT_ROOT}"
    exit 1
fi
# 校验Drush可执行文件
if [ ! -x "${DRUSH_BIN}" ]; then
    echo "ERROR: Drush 不存在或无执行权限 ${DRUSH_BIN}"
    exit 1
fi
# 切换到项目根目录执行（多站点别名必须在项目根运行）
cd "${PROJECT_ROOT}" || exit 1
# 透传所有参数
exec "${DRUSH_BIN}" "$@"
EOF


###### 赋予执行权限
chmod +x /var/www/Drupal_Core/drush/drush-wrap

###### 一次性写入自动创建软链配置（仅执行这一次）
echo 'ln -sf /var/www/Drupal_Core/drush/drush-wrap /usr/local/bin/drush 2>/dev/null' >> /etc/profile

###### 加载软链配置
source /etc/profile

2. 添加执行权限、重建全局软链

# 添加脚本执行权限
chmod +x /var/www/Drupal_Core/drush/drush-wrap 

# 清理旧软链
rm -f /usr/local/bin/drush 

# 生成全局有效软链
ln -sf /var/www/Drupal_Core/drush/drush-wrap /usr/local/bin/drush

3. 容器重启自动恢复软链（持久化配置，无冗余嵌套）

echo 'ln -sf /var/www/Drupal_Core/drush/drush-wrap /usr/local/bin/drush' >> /etc/profile
source /etc/profile

1.1.2 多站点 Drush 别名配置（标准规范）

适配 nojjj.com、qqrss.com 多站点架构，root 统一填写 Drupal 核心 web 目录，通过 uri 区分独立站点（禁止指向 sites/域名子目录），支持简写/完整双别名调用。

方式一：Cat 快速写入（推荐，格式标准无错乱）

cat > /var/www/Drupal_Core/drush/sites/self.site.yml <<'EOF'
nojjj:
  root: /var/www/Drupal_Core/web
  uri: https://nojjj.com
  config:
    sync: sites/nojjj.com/files/deploy_config/sync

qqrss:
  root: /var/www/Drupal_Core/web
  uri: https://qqrss.com
  config:
    sync: sites/qqrss.com/files/deploy_config/sync
EOF

方式二：Echo 逐行写入（适配分步执行场景）

> /var/www/Drupal_Core/drush/sites/self.site.yml

echo "nojjj:" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  root: /var/www/Drupal_Core/web" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  uri: https://nojjj.com" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  config:" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "    sync: sites/nojjj.com/files/deploy_config/sync" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "qqrss:" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  root: /var/www/Drupal_Core/web" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  uri: https://qqrss.com" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "  config:" >> /var/www/Drupal_Core/drush/sites/self.site.yml
echo "    sync: sites/qqrss.com/files/deploy_config/sync" >> /var/www/Drupal_Core/drush/sites/self.site.yml

最终规范目录结构

/var/www/Drupal_Core/drush/
├─ drush-wrap        # 全局Drush启动脚本（多站点适配）
└─ sites/
   └─ self.site.yml  # 多站点别名配置文件

4. 环境校验命令（确认配置生效）

# 查看所有多站点别名
drush site:alias

# 查看Drush版本
drush --version

# 校验单个站点状态
drush @nojjj core:status
drush @qqrss core:status

# 测试缓存重建
drush @nojjj cr
drush @qqrss cr

1.2 全量数据备份（必做）

更新前备份代码文件与数据库，防止版本更新失败、代码回滚无依据，适配 HTML 文章站点数据保全需求。

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

# 分站点备份数据库（多站点专用）
drush @nojjj sql-dump --ordered-dump --gzip --result-file=nojjj_db_$(date +%Y%m%d).sql.gz
drush @qqrss sql-dump --ordered-dump --gzip --result-file=qqrss_db_$(date +%Y%m%d).sql.gz

备份完成后，建议优先在测试环境验证更新流程，无误后再操作生产站点。

1.3 开启站点维护模式

生产环境更新必须开启维护模式，避免用户访问导致数据错乱、页面报错，支持分站点单独开启。

# 单个站点开启维护模式
drush @nojjj state:set system.maintenance_mode 1
drush @qqrss state:set system.maintenance_mode 1

# 更新完成后关闭命令
# drush @nojjj state:set system.maintenance_mode 0
# drush @qqrss state:set system.maintenance_mode 0

1.4 模块兼容性检测（适配HTML静态站点）

使用官方升级检测模块，扫描所有主题、插件兼容性，避免更新后 HTML 页面渲染异常、功能失效。

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

检测地址：/admin/reports/upgrade-status，重点确认已启用模块、页面渲染组件、HTML模板完全兼容 Drupal11。

1.5 预更新第三方模块/主题

提前更新所有贡献模块与模板，规避核心更新后的依赖冲突，保证 HTML 文章、页面布局正常渲染。

# 查看待更新模块
composer outdated "drupal/*"

# 批量更新所有第三方模块（含依赖）
composer update drupal/* --with-dependencies

二、Drupal 11 核心版本更新流程

2.1 版本约束规则说明

^11 通配约束：如 ^11.2，可直接升级 11.2.x、11.3.x 小版本，无需修改配置文件
固定版本约束：如 11.1.0，需手动修改版本号后再执行更新

2.2 分场景核心更新命令

场景1：小版本迭代（11.2.x → 11.3.x，常用）

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

场景2：指定固定目标版本

composer require 'drupal/core-recommended:^11.3' -W

场景3：Drupal10 跨版本升级至 Drupal11

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

composer update --dry-run

2.3 数据库更新（核心步骤）

核心代码更新后，必须执行数据库迁移脚本，适配新版内核数据表结构，保证文章、页面数据正常读取。

# 交互式更新（手动确认）
drush @nojjj updatedb
drush @qqrss updatedb

# 自动化更新（生产脚本专用）
drush @nojjj updatedb -y
drush @qqrss updatedb -y

2.4 配置导入与缓存清理

同步站点配置、清理静态缓存，解决 HTML 页面缓存残留、新旧代码不兼容问题。

# 导入站点配置
drush @nojjj config:import -y
drush @qqrss config:import -y

# 重建全站缓存
drush @nojjj cache:rebuild
drush @qqrss cache:rebuild

2.5 一键部署命令（Drupal11 最优方案）

drush deploy 自动串联所有部署步骤，适配 HTML 静态站点快速上线，执行顺序：数据库更新 → 配置导入 → 缓存重建 → 钩子执行 → 缓存预热。

drush @nojjj deploy -y
drush @qqrss deploy -y

三、生产环境标准更新流程（速查表）

步骤	执行命令	操作说明
1	`drush @站点名 state:set system.maintenance_mode 1`	开启维护模式，阻断用户访问
2	`drush @站点名 cr`	初始化清理旧缓存
3	`composer update drupal/core-recommended --with-dependencies`	更新Drupal核心代码
4	`drush @站点名 deploy -y`	一键完成数据库、配置、缓存更新
5	`drush @站点名 state:set system.maintenance_mode 0`	关闭维护模式，恢复站点访问
6	站点前后端人工核验	验证HTML页面、文章功能正常

四、更新后全维度验证（HTML站点专属）

前端页面验证：访问站点首页、文章详情页、静态HTML页面，确认无白屏、错乱、样式丢失
后台登录验证：登录 /user/login，确认后台功能、内容编辑、发布功能正常
核心功能验证：测试文章发布、HTML内容修改、菜单导航、页面加载等核心流程
系统状态验证：访问/admin/reports/status，无系统报错、版本信息正常
更新状态验证：访问 /admin/reports/updates，确认核心版本为最新 11.3.x

五、常见故障排查（适配多站点HTML站点）

Q1：更新后页面白屏、HTML渲染异常

优先执行 drush @站点名 cr 清理缓存；若无效，开启详细错误日志排查：

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

Q2：Composer 依赖冲突更新失败

精准定位冲突模块，排查不兼容的旧版插件/主题：

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：多站点别名命令失效

确认 self.site.yml 格式规范（缩进为2个空格）、root 指向 /var/www/Drupal_Core/web，重新执行 drush site:alias 刷新别名缓存。

六、结语

Composer+Drush 是 Drupal 官方唯一标准更新方案，适配多站点架构与纯 HTML 文章站点。整套流程解决了版本升级、缓存异常、页面渲染错乱、多站点命令失效等核心问题，兼顾手动运维与自动化部署场景，可直接用于生产环境常态化迭代。