使用 Drush 升级

Drush 是 Drupal 的命令行外壳和脚本接口。使用 Drush 升级到 Drupal 8 是使用浏览器用户界面的替代方案。对于复杂站点的迁移，使用 Drush 升级到 Drupal 8 非常有用，因为它允许逐个运行迁移并支持回滚。

使用 Composer 安装 Drush

Drupal 8 站点可以使用 Composer 构建。如果您决定使用 drupal-composer/drupal-project 作为 Composer 项目模板，那么您已经拥有 Drush，因为它在项目的 composer.json 文件中被定义为依赖。

如果您的 Composer 项目中没有将 Drush 定义为依赖，可以通过以下命令行安装 Drush：

composer require drush/drush

注意：现在请使用 Drush 9

由于 Drush 10 存在问题，目前推荐通过 composer 安装 Drush 9：drush/drush:^9.0，这将安装到 9.7.2 版本。 

这样您将获得最新（稳定）的 Drush，它应当与最新的 Drupal 兼容。更多信息请参阅 Drush 与 Drupal 版本兼容性矩阵。

检查 Drush 版本：

drush --version

Drupal 必需模块

要使用 Drush 进行迁移，您需要下载并启用以下附加模块：

• Migrate Upgrade：为从 Drupal 6 或 7 升级到 Drupal 8 提供 Drush 支持。
• Migrate Plus：为迁移引擎的基本功能提供扩展。
• Migrate Tools：提供本页面稍后会用到的 Drush 命令。

重要！ 请特别注意为这三个模块选择正确的版本。请查看项目页面，选择与您的 Drupal 8 核心版本兼容的版本。

有关不同升级模块的更多信息，请参阅 升级模块列表。

定义源数据库

以下示例展示了如何定义您的 Drupal 6/7 源站点数据库的连接信息。如果您的源站点使用了数据库前缀，请务必提供前缀。您需要同时连接本地开发数据库（默认）和源数据库（D6 或 D7）。下面给出了 Lando 的示例，其中也包含了默认数据库配置以供参考。

注意： 为避免问题，重要的是将迁移数据库键命名为 migrate，参见 迁移时 Drupal 7 核心字段错误问题。

settings.php 中的数据库连接示例

$databases['default']['default'] = [
  'database' => 'drupal8',
  'username' => 'drupal8',
  'password' => 'drupal8',
  'prefix' => '',
  'host' => 'database',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

$databases['migrate']['default'] = [
  'database' => 'drupal7db',
  'username' => 'drupal7db',
  'password' => 'drupal7db',
  'prefix' => '',
  'host' => 'd7db',
  'port' => '3306',
  'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
  'driver' => 'mysql',
];

Example .lando.yml

name: mywebsite
recipe: drupal8
config:
  webroot: web

# 创建 Drupal 7 数据库服务，可以考虑添加 phpmyadmin
services:
  d7db:
    type: mariadb
    creds:
      user: drupal7db
      password: drupal7db
      database: drupal7db
    portforward: true

导入 Drupal 7 数据库，假设数据库转储文件名为 mywebsite_db.sql.gz 并位于当前文件夹：

lando db-import --host=d7db --user=drupal7db mywebsite_db.sql.gz

灵感来源：https://github.com/thinktandem/migration_boilerplate.

使用 migrate-upgrade 生成迁移

Migrate Tools 模块会添加 Drush 命令，例如 drush migrate-status 和 drush migrate-import。完整命令列表见本文档底部。

如果您在未做任何操作时尝试运行 drush migrate-status，不会看到任何可用的迁移。这是因为必须先基于源数据库生成迁移。由于 Migrate 不知道使用哪个源，因此迁移尚未生成。

要生成迁移，您需要使用由 Migrate Upgrade 模块提供的 Drush 命令 drush migrate-upgrade。

通常您会希望只生成单个迁移，以便逐个运行。如果是这样，您需要使用 --configure-only 参数：

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-root=http://example.com --configure-only 

其中：

• 'user' - 源数据库的用户名。
• 'password' - 源数据库用户密码。
• 'server' - 源数据库服务器。
• 'db' - 源数据库。
• 'http://example.com' - 源站点根目录。如果源站点位于本地文件系统，可以使用 Drupal 根目录的路径作为此参数的值。此值将被附加到单个文件路径，用于查找并导入它们。

选项 --legacy-db-key 允许您使用 settings.php 中定义的 $database 数组键。

如果源站点使用了表前缀，您需要额外添加参数。例如数据库前缀是“drupal_”：

drush migrate-upgrade --legacy-db-url=mysql://user:password@server/db --legacy-db-prefix=drupal_ --legacy-root=http://example.com --configure-only 

如果不使用 --configure-only，drush migrate-upgrade 会先生成迁移并立即执行。

在使用 --configure-only 运行 migrate-upgrade 后，可以运行 migrate-status 查看可能的迁移列表：

drush migrate-status

然后您可以检查并选择性地执行这些迁移。要单独运行某个迁移：

drush migrate-import <migration name> 

要运行列表中的所有迁移：

drush migrate-import --all 

使用 migrate-manifest 启动特定迁移

您也可以使用 manifest 文件来定义要运行的迁移集合。这允许可重现地运行迁移组。此方法需要 Migrate Manifest 模块。安装后，您可以通过以下命令获取所有可用迁移列表：

drush migrate-template-list # Drush 8

或

drush migrate:template:list # Drush 9

注意：Migrate Manifest 目前与 Drush 10+ 并不完全兼容。

所需迁移在 YAML 文件中定义，如下所示。您只需列出所需迁移，Migrate Manifest 会提示您添加满足依赖所需的其他迁移。迁移可以按任意顺序列出，它们将按依赖关系正确运行。

# user 
- d6_user 
- d6_user_profile_field 
- d6_user_profile_field_instance 
- d6_user_profile_entity_display 
- d6_user_profile_entity_form_display 
- d6_profile_values:user 
- d6_filter_format 
- d6_user_role 
- d6_user_picture_entity_display 
- d6_user_picture_entity_form_display 
- d6_user_picture_file 
- d6_user_picture_field 
- d6_user_picture_field_instance 

# taxonomy 
- d6_taxonomy_vocabulary 
- d6_taxonomy_settings 
- d6_taxonomy_term 

# nodes 
- d6_node 
- d6_node_revision 
- d6_node_type 
- d6_view_modes 
- d6_filter_format 
- d6_field_instance_per_form_display 
- d6_field_instance_widget_settings 
- d6_field_formatter_settings 
- d6_field_instance 
- d6_field 
- d6_field_settings 
- d6_node_settings 
- d6_cck_field_values:* 
- d6_cck_field_revision:* 

# taxonomy fields 
- d6_term_node_revision 
- d6_term_node 
- d6_vocabulary_entity_display 
- d6_vocabulary_entity_form_display 
- d6_vocabulary_field_instance 
- d6_vocabulary_field 

# blocks 
- d6_block 
- d6_menu 

# custom blocks 
- d6_custom_block 
- d6_filter_format 

# book 
- d6_book 
- d6_book_settings 

# file migrations are configurable, see https://www.drupal.org/node/2257723 
- d6_file: 
    source: 
      conf_path: sites/assets 
    destination: 
      source_base_path: destination/base/path 
      destination_path_property: uri 

将 manifest 文件放在运行 Drush 时可访问的位置。建议将其保存在版本控制系统中，以便跟踪迁移的变更。

确保 manifest 文件列出的迁移所依赖的模块存在并在源站点启用（例如 d6_field 所需的字段模块）。否则执行迁移时会出现错误。

manifest 文件定义的迁移通过命令行运行，如下所示。替换数据库 URL 和 manifest 文件路径：

drush migrate-manifest --legacy-db-url=mysql://d6user:d6pass@localhost/drupal_6 manifest.yml 

Acquia Dev Desktop 用户注意事项

如果您使用 Acquia Dev Desktop 并且在其中有 Drupal 6 站点，默认数据库凭据是 drupaluser（无密码），数据库运行在 127.0.0.1:33067。这样，在命令中 --legacy-db-url=mysql://drupaluser:@127.0.0.1:33067/drupal_6 就能工作。数据库名假设为 drupal_6。如果连接有问题，请运行 drush status 检查这些值。

Drush 迁移命令参考

migrate-upgrade（无别名）

由 Migrate Upgrade 提供。用于从 Drupal 6/7 升级到 Drupal 8。此命令会基于源站点配置和内容生成迁移配置。

示例

drush migrate-upgrade --legacy-db-key=migrate

选项

• legacy-db-url：源数据库的连接信息。
• legacy-db-prefix：源数据库表前缀。
• legacy-root：源站点路径，用于从文件目录迁移内容。如果文件是私有的，需要指定本地文件路径；公共文件也可以使用 http(s)。
• configure-only：仅生成迁移配置。当此选项启用时，迁移会生成，但需使用 “drush migrate-import” 单独运行。

migrate-status (ms)

由 Migrate Tools 提供。用于获取所有迁移及其状态。

drush migrate-status

migrate-import (mi)

由 Migrate Tools 提供。用于执行迁移，常用于自定义迁移。

drush migrate-import migration_id
drush migrate-import --group=files

选项

• all：运行所有已配置迁移。
• group：运行某个组的所有迁移。
• limit：限制迁移中每批处理的项目数量。
• feedback：显示进度的频率。
• idlist：逗号分隔的源 ID 列表。
• update：迁移新项目以及源中已更新的项目。
• force：强制运行操作，即使依赖未完成。

常见使用场景

• 当使用 migrate-upgrade --configure-only 时，会创建配置对象。由于 Drupal 8 默认不允许覆盖现有配置，因此需要使用 migrate-import 来运行迁移。
• 当创建并导入自定义迁移（通过配置管理 UI 或 drush config-import）后，需要使用 migrate-import 来运行。

migrate-rollback (mr)

由 Migrate Tools 提供。用于回滚迁移，常用于测试或重置。

drush migrate-rollback migration_id
drush migrate-rollback --group=files

migrate-stop (mst)

由 Migrate Tools 提供。用于停止活跃迁移。

drush migrate-stop migration_id

migrate-reset-status (mrs)

由 Migrate Tools 提供。用于将活跃迁移重置为等待状态。

drush migrate-reset-status migration_id

migrate-messages (mmsg)

由 Migrate Tools 提供。用于查看迁移过程中的消息，帮助诊断失败。

drush migrate-messages migration_id

migrate-fields-source (mfs)

由 Migrate Tools 提供。用于列出源可映射的字段。

drush migrate-fields-source migration_id