升级到 Drupal 8 时的迁移配置

01/10/2025, by Ivan

创建你的初始迁移

使用 drush migrate-upgrade --configure-only 创建迁移，如使用 Drush 升级部分所述。
确保你有一个 config/sync 目录，下一步会写入其中。
使用 drush config:export 导出迁移。
创建你自己的迁移模块。
从 config/sync 目录中复制你要使用的 YML 文件到新自定义模块的 config/install 目录，并根据需要编辑它们以删除 uuid 值并修改 id、group、label 等。
从 config/sync 复制 migrate_plus.migration_group.migrate_drupal_7.yml 文件到新自定义模块的 config/install 目录，并将其命名为 migrate_plus.migration_group.your_module.yml。这个分组文件是必须的，因为它包含数据库设置。

管理迁移

先从用户角色和用户的迁移开始，然后再迁移节点。
继续将文件添加到 config/install 目录后，可以使用类似 drush config-import --partial --source=modules/custom/your_module/config/install 的命令重新导入目录（需要启用 Config 模块）。

升级到 Drupal 8 时重命名字段

假设你在 Drupal 7 站点上有一个内容类型 A，包含字段 foo、bar 和 baz。假设你想在 Drupal 8 中将 baz 字段重命名为 zot。这类修改在使用 drush 升级时相对容易完成。

使用 drush migrate-upgrade --configure-only 创建迁移，如上文所述。
运行节点类型和字段迁移。这会生成内容类型 A 和字段 foo、bar 和 baz。
在 Drupal 8 中手动创建字段 zot。删除迁移创建的 baz 字段（因为你不打算使用它）。
使用 Migrate Plus 模块可以将迁移作为配置对象实现，从而灵活加载、修改和保存它们。通过 drush migrate-upgrade --configure-only 创建的单个迁移可以在 admin/config/development/configuration/single/export 中查看，并选择「Migration」作为配置类型，然后选择节点 (A) 的迁移。
复制并粘贴迁移到 admin/config/development/configuration/single/import，但修改字段映射，将目标字段改为 field_zot，同时保持源字段为 field_baz。具体定义取决于字段类型。要理解迁移的结构，请参阅 Migrate API 文档中的示例。
导入修改后的迁移后，可以使用 Drush 运行内容类型 A 的迁移，并验证数据是否已正确迁移到 zot 字段。
如果你还要迁移节点修订版本，请对节点修订迁移重复该字段映射修改。

另一种方法是如上所述手动创建新字段 zot，并通过实现 hook_migration_plugins_alter() 修改节点 (A) 的迁移字段映射。

编写自定义过程插件

如果你需要定义自定义转换逻辑（如果满足条件就执行某操作），你可以考虑编写自己的过程插件。

Migrate API 文档中的示例以用户迁移为例。确定用户语言代码需要 if-else 逻辑，因此 User 模块提供了自己的过程插件 UserLangocode。

上述示例描述了如何将过程插件保存在 MODULE/src/Plugin/migrate/process 目录下，并通过注解来启用使用。在编写你自己的插件时，可以参考 UserLangcode 和其他过程插件。

hook_migrate_prepare_row()

如果你需要定义自定义转换逻辑，还可以在自定义模块中实现 hook_migrate_prepare_row() 并在其中编写逻辑。

根据 API 文档，该 hook 有三个参数：

你可以使用 $migration->id() 将逻辑限制到特定的迁移。

要读取源属性到变量，请使用 Row::getSourceProperty()。例如，如果源行中有一个名为 type 的属性，可以这样写：$type = $row->getSourceProperty('type');

要设置一个全新的属性供迁移定义作为源使用，请使用 Row::setSourceProperty()。

要向源站点执行数据库查询，请使用 $source->getDatabase()->query()，如 API 文档所示。

要跳过某一行的迁移，可以抛出新的 MigrateSkipRowException。

hook_migration_plugins_alter()

另一种自定义迁移的方式是在自定义模块中实现 hook_migration_plugins_alter()。

根据 API 文档，这个 hook 有一个参数，即所有已发现迁移的关联数组。你可以修改迁移或删除你不想执行的迁移。

Migrate Plus 提供 PREPARE_ROW 事件

如果你更喜欢使用面向对象的方式为核心 prepare_row 处理器编写自定义响应，而不是实现 hook_migrate_prepare_row()，你可以在启用 Migrate Plus 模块后这样做。Migrate Plus 提供了 PREPARE_ROW 事件，你的订阅者可以监听该事件。有关 Drupal 8 事件的 API 文档，请参阅官方文档。若要查看事件订阅者的实现示例，可以参考 Simple FB Connect 模块手册中的示例。

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

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