通过 Composer 更新核心

06/10/2025, by Ivan

更新至 Drupal 8.8.0 或更高版本时遇到问题？
在 Drupal 8.8.0 中，Composer 管理方式发生了关键性变化，这些改进将长期提升 Drupal 网站的依赖管理体验。然而，从旧版本升级时可能会遇到一些兼容性问题。

准备工作

要了解 Composer 如何管理 Drupal 依赖，请参阅在 Drupal 中使用 Composer。如果您还不确定是否应通过 Composer 进行更新，请比较不同的更新方法。

为方便操作，这里还包括 Drush 命令，用于执行数据库更新和缓存清理等任务——许多用户认为 Drush 比管理界面更快速高效。

如果您的现有 Drupal 网站从未使用过 Composer，请首先确保它已准备好支持 Composer 管理。

更新 Drupal 8 核心

首先，检查 Drupal 核心是否有可用更新：

composer update --dry-run "drupal/*"

此命令会显示可用的次要更新或补丁更新；若要检测主要版本更新，请使用 composer "drupal/*"。如果输出中没有以 drupal/core 开头的行，则说明 Composer 未检测到可用更新。如果出现 drupal/core-recommended，则表示可更新，请继续以下步骤。

一键更新方法

如果您熟悉 Drupal 更新流程，并了解所需的预防措施，更新命令如下：

composer update drupal/core --with-dependencies
drush updatedb
drush cache:rebuild

如果您的项目使用的是 core-recommended 包，请将 drupal/core 替换为 drupal/core-recommended。您可以在 composer.json 或 composer update --dry-run 输出中确认这一点。

若您的网站是基于 drupal-composer/drupal-project 模板创建的，上述命令可能无法直接执行。请参阅以下说明。

更新至 Drupal 8.8.0 或更新版本

最新的 drupal-composer/drupal-project 模板与 Drupal 8.8.x 兼容。但如果您在 2019 年或更早版本中使用该模板创建网站，则在首次升级至 8.8.0 或更高版本时，需要进行一次性调整，详见下文“特别说明”。

未通过 Composer 安装 Drupal 的用户

如果您的 Drupal 不是通过 Composer 安装的，必须先将网站转换为 Composer 管理项目，才能使用 Composer 进行更新。请参阅为现有网站添加 Composer 支持，了解手动集成步骤。

逐步更新指南

使用 Composer 更新 Drupal 核心的完整步骤如下：

备份文件和数据库。
使用 drush sql:dump 导出数据库。由于 Drush 9 已删除 archive-dump 命令，请使用常规 CLI 工具备份文件（通常不包括 vendor 目录）。
阅读 Drupal 核心发行说明。某些模块或主题可能需要更新以兼容新的次要版本。补丁版本通常不需要。
启用维护模式：设置 system.maintenance_mode 1，然后运行 drush cache:rebuild。
如果部分模块或主题需要更新，请参考模块更新指南。
运行 Composer 更新核心及依赖项：

composer update drupal/core --with-dependencies

如果您使用的是 drupal/core-recommended 模板，请替换为该包。若网站是从 drupal-composer/drupal-project 创建的，请参考后续特别说明。

运行数据库更新 drush updatedb 并清理缓存 drush cache:rebuild。
若使用配置管理部署，请在数据库更新后运行 drush config:export --diff 导出配置（部分核心更新可能修改配置结构或新增值）。
验证网站状态：查看状态报告是否有错误，检查数据库日志模块是否记录了警告。
关闭维护模式：drush state:set system.maintenance_mode 0，然后运行 drush cache:rebuild。
以匿名用户身份访问网站，确认功能正常。

生产环境中的更新

无需重复上述步骤。运行 composer install 即可根据 composer.lock 安装固定版本的依赖。
若使用分离的开发 / 预发布 / 生产环境，请确保同步 composer.json 和 composer.lock 文件，并在生产环境执行 composer install --no-dev。该参数会跳过安装 require-dev 中的调试和测试包。

更新至 Drupal 8.8.0 的特别说明

Drupal 官方测试合作伙伴 PreviousNext 发布了详细的博客，介绍了他们从 8.7 升级到 8.8.0 beta 的经验，可供参考。

升级至 8.8.0 时出现的问题主要源自迁移到新的官方模板 drupal/recommended-project。请参考以下排查步骤以确保平滑升级。

删除 vendor 目录

删除 vendor 目录可解决部分依赖冲突：

cd your_install_dir
rm -rf vendor

从 webflo/drupal-core-strict 迁移到 drupal/core-recommended

旧版网站使用 webflo/drupal-core-strict 锁定依赖版本。自 8.8.0 起，官方提供 drupal/core-recommended 替代。迁移步骤如下：

composer update
git add composer.lock; git commit
composer remove webflo/drupal-core-strict --no-update
composer remove drupal/core --no-update
composer require 'composer/installers:^1.7' --no-update
rm composer.lock
rm -rf vendor
composer require drupal/core-recommended:^8.8 --update-with-dependencies
git add composer.json composer.lock; git commit -m "Update Drupal to 8.8.0 using drupal/core-recommended"

从 webflo/drupal-core-require-dev 迁移到 drupal/core-dev

旧网站可能使用 webflo/drupal-core-require-dev 管理开发依赖。请改为使用 drupal/core-dev：

composer remove --dev webflo/drupal-core-require-dev

如果需要重新安装开发工具：

composer require --dev drupal/core-dev

更新补丁

若使用 cweagans/composer-patches 应用补丁，可能需重新滚动补丁并更新 composer.json 中的 extra/patches 配置。

更新冲突依赖

如果某些依赖与新版 Drupal 不兼容，可通过 composer require 临时指定版本更新核心：

composer require --update-with-dependencies \
drupal/core:^8.8.0 \
symfony/finder:^3.4 \
symfony/filesystem:^3.4

然后为开发依赖运行：

composer require --dev --update-with-dependencies \
drupal/core-dev:^8.8.0 \
symfony/debug:^3.4

最后删除临时依赖：

composer remove -n symfony/finder symfony/filesystem
composer remove -n --dev symfony/debug

更新数据库与配置

drush updb
drush cr
drush config-export

更新 settings.php

从 Drupal 8.8.0 开始，配置同步目录应定义在 $settings 而非 $config_directories。

请将以下内容：

$config_directories['sync'] = 'foo/bar';

修改为：

$settings['config_sync_directory'] = 'foo/bar';

已知问题与解决方案

若执行 composer update 后 drupal/core 未更新，可能是其他依赖阻止更新。使用 composer prohibits 检查。例如：

composer prohibits drupal/core:8.5.0

更新这些依赖后再次尝试。例如：

composer update drupal/core "symfony/*" --with-dependencies

Composer 更新问题通常由旧模板或 composer.json 设置错误引起。请确保使用官方推荐模板（参考 Drupal 用户指南第 3.5 章：使用 Composer 下载与更新文件）。

自 2020 年 1 月起，drupal-composer/drupal-project 不再推荐用于 Drupal 8.8+。请参阅社区指南：使用 Composer 模板启动网站。

额外区块类型 (EBT) - 全新的布局构建器体验❗

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验