随着Drupal 8在2021年底正式结束生命周期，将系统升级到Drupal 10成为保障网站安全与获取新功能的关键。Drupal 8到10的跨越式升级并非直接跳转，而是需通过Drupal 9过渡，这一过程涉及环境适配、模块兼容、代码重构等多维度工作。本文将从准备到落地，详解Drupal 8升级到10的全流程攻略，助力开发者高效完成架构迁移。

所谓“跨越式升级”，是指Drupal 8无法直接升级至10，需先过渡到Drupal 9，再升级至10。这一设计源于Drupal的语义化版本控制策略：Drupal 9作为8的“清理版”，移除了8中的废弃API并强化兼容性，而Drupal 10则基于9引入全新架构（如Symfony 6、Twig 3）和性能优化。类比建筑翻新，Drupal 9是“拆除旧结构”，Drupal 10是“搭建新框架”，二者共同构成Drupal升级的完整路径。

升级前准备：环境与兼容性评估

环境依赖兼容性检查

Drupal 9和10对运行环境有明确要求，需提前验证服务器配置。例如，Drupal 9最低支持PHP 7.3（推荐7.4+），而Drupal 10则要求PHP 8.1+，且需适配MariaDB 10.3+或PostgreSQL 12+。可通过php -v和数据库管理工具确认版本，同时确保Composer 2.0+已安装，避免依赖解析错误。

模块与主题兼容性评估

contrib模块和自定义模块是升级的核心障碍。需通过Drupal.org模块页面检查contrib模块是否标有“Drupal 9/10兼容”标签，自定义模块则需通过Drupal模块开发工具（如Upgrade Status模块）扫描过时API调用，例如是否仍在使用entity_load()（Drupal 8中已废弃，Drupal 9/10需用\Drupal::entityTypeManager()->getStorage()->load()）。

从Drupal 8到9的过渡：核心升级与依赖处理

核心升级步骤：基于Composer的平滑迁移

1. 备份代码与数据库：通过drush sql-dump > backup.sql备份数据，版本控制工具（如Git）提交当前代码；
2. 更新Composer配置：移除composer.json中对Drupal 8核心的锁定，执行composer require drupal/core-recommended:^9.0 --update-with-dependencies；
3. 处理依赖冲突：若出现模块版本不兼容，需升级对应contrib模块至Drupal 9版本（如Views Bulk Operations需升级至4.0+）；
4. 执行数据库更新：运行drush updb同步架构变更，清除缓存drush cr。

代码适配：移除废弃API与依赖重构

自定义模块中需重点重构以下内容：
- 移除对drupal_set_message()的调用，改用\Drupal\Core\Messenger\MessengerInterface；
- 将hook_menu()路由定义迁移至*.routing.yml文件；
- 替换过时的表单构建函数，例如FormStateInterface::getValue()替代$form_state->getValue()（需类型提示）。

// Drupal 8 过时代码
function custom_module_menu() {
  $items['custom-path'] = [
    'title' => 'Custom Page',
    'page callback' => 'custom_module_page',
    'access arguments' => ['access content'],
  ];
  return $items;
}

// Drupal 9/10 推荐代码（custom_module.routing.yml）
custom_module.custom_path:
  path: '/custom-path'
  defaults:
    _controller: '\Drupal\custom_module\Controller\CustomController::page'
    _title: 'Custom Page'
  requirements:
    _permission: 'access content'

从Drupal 9到10的升级：关键变化与功能适配

核心依赖升级：Symfony 6与PHP 8.1+特性

Drupal 10基于Symfony 6构建，需适配其命名空间变更（如Symfony\Component\HttpFoundation\Request保持不变，但部分组件方法签名调整）；同时需兼容PHP 8.1+特性，例如支持命名参数（如Database::select('node', 'n', ['fetch' => \PDO::FETCH_ASSOC])可简化为Database::select('node', 'n', fetch: \PDO::FETCH_ASSOC)）。此外，Twig 3要求模板中变量输出必须使用{{ item.content }}替代Drupal 9中的{{ item }}（针对Render Array渲染）。

模块与主题适配清单

• 移除废弃模块：Drupal 10删除了Color、Quick Edit等核心模块，需通过contrib模块替代（如Color.module可迁移至Color Field模块）；
• PSR-4自动加载：自定义模块必须采用PSR-4规范，确保src/目录下的类可被自动加载；
• 主题模板更新：Twig 3不再支持{% spaceless %}标签，需替换为{% apply spaceless %}；
• 配置实体重构：ConfigEntityInterface::save()返回类型变为int，需确保自定义配置实体调用时处理返回值。

升级后验证与优化：确保系统稳定运行

完成升级后，需通过以下步骤验证系统：
1. 功能测试：使用Drupal Simpletest或PHPUnit执行单元测试，重点验证自定义模块的核心功能（如数据提交、权限控制）；
2. 性能监控：通过Devel模块检查数据库查询效率，启用Redis缓存优化加载速度；
3. 安全加固：安装Security Review模块扫描权限漏洞，订阅Drupal安全公告（drupal.org/security）确保及时响应补丁。

结语：Drupal升级的长期价值与实践思考

Drupal升级不仅是版本迭代，更是系统架构的现代化转型。通过从8到9再到10的过渡，网站将获得更优的性能、更强的安全支持，以及对最新Web标准的适配。在Drupal开发中，提前采用@deprecated注解标记过时代码、持续跟进模块兼容性列表，可大幅降低升级成本。

你在Drupal 8升级到10的过程中，是否遇到过自定义模块API重构的复杂场景？对于依赖大量contrib模块的网站，你认为优先升级核心还是模块更能保障升级效率？欢迎在评论区分享你的实践经验！