文档Commerce升级指南

下载Upgrade Compatibility Tool

Last update: Thu Jul 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 有经验的
  • 管理员
  • 开发人员
NOTE
Upgrade Compatibility Tool仅适用于Adobe Commerce实例。

要在命令行界面中开始使用Upgrade Compatibility Tool，请通过运行以下命令下载它：

composer create-project magento/upgrade-compatibility-tool uct --repository https://repo.magento.com

您可能需要使用chmod命令授予工具可执行文件的权限：

chmod +x ./uct/bin/uct

命令行界面中的Upgrade Compatibility Tool

Upgrade Compatibility Tool是一种通过分析其中安装的所有模块来针对特定版本检查Adobe Commerce自定义实例的工具。 它会返回在升级到最新版本的Adobe Commerce之前必须解决的严重问题、错误和警告列表。

请参阅此视频教程 (06:02)，了解有关Upgrade Compatibility Tool的更多信息。

命令行界面中Upgrade Compatibility Tool的可用命令：

命令
描述
upgrade:check
此命令通过分析其中安装的所有模块运行Upgrade Compatibility Tool。
dbschema:diff
此命令显示两个指定的Adobe Commerce版本之间数据库架构的所有差异。
core:code:changes
此命令会将您当前的Adobe Commerce安装与干净的vanilla安装进行比较。
refactor
此命令会自动修复一组减少的问题。
graphql:compare
此命令提供选项，用于内检两个GraphQL端点并比较其架构。
list
此命令返回所有Upgrade Compatibility Tool可用命令的列表。
help
此命令返回Upgrade Compatibility Tool的所有可用help选项。 此命令也可以与以前的命令一起运行选项。

使用upgrade:check命令

upgrade:check命令检查该特定Adobe Commerce实例的核心代码更改以及其中安装的所有自定义代码更改。

upgrade:check命令是执行该工具的主命令：

bin/uct upgrade:check <dir>

其中，<dir>值是Adobe Commerce实例所在的目录。

upgrade:check命令的可用选项：

命令
可用选项
upgrade:check
  • —help：返回所有可用选项。
  • —current-version：当前的Adobe Commerce版本。 此参数是必需的，必须始终使用。
  • — 最小问题级别：您可以根据最小问题级别筛选问题（默认值为“警告”）。
  • —ignore-current-version-compatibility-issues（或 — i）：如果不想在报表中包含来自当前版本的严重问题、错误和警告。
  • — 即将推出的版本（或 — c）：定位特定的Adobe Commerce版本。 如果省略，将使用最新可用的。

Upgrade Compatibility Tool允许您运行带有--ignore-current-version-compatibility-issues选项的upgrade:check命令。 当您只想在Upgrade Compatibility Tool报表中获取从当前版本更新到目标版本时引入的新问题时，可使用此选项：

bin/uct upgrade:check --ignore-current-version-compatibility-issues <dir>
NOTE
这仅适用于PHP API验证。

添加--coming-version选项

您可以使用--coming-version选项将当前Adobe Commerce安装与任何Adobe Commerce版本>=2.3进行比较。

运行upgrade:check命令时必须提供版本作为参数：

bin/uct upgrade:check <dir> -c 2.4.3

其中-c, --coming-version[=COMING-VERSION]引用Adobe Commerce目标版本。

运行--coming-version时存在一些限制：

  • 此参数是指可识别特定版本Adobe Commerce的任何标记。
  • 需要明确提供此值；仅提供其值不起作用。
  • 提供不带任何引号（单引号或双引号）的标记版本： '2.4.1-develop'。
  • 您不应提供比您当前安装的版本更旧的版本，也不应提供比2.3更旧的版本，后者是目前支持的最旧的版本。

使用dbschema:diff命令

您可以检索两个Adobe Commerce版本的数据库架构之间的差异。

bin/uct dbschema:diff <current-version> <target-version>

其中参数如下：

  • <current-version>：要比较的任何Adobe Commerce版本。
  • <target-version>：还有任何Adobe Commerce版本用于比较。

执行示例：

bin/uct dbschema:diff 2.4.3 2.4.3-p3

DB schema differences between versions 2.4.3 and 2.4.3-p3:

Table klarna_payments_quote constraint QUOTE_ID_KLARNA_PAYMENTS_QUOTE_QUOTE_ID_QUOTE_ENTITY_ID is present only in version 2.4.3-p3
Table klarna_payments_quote index KLARNA_PAYMENTS_QUOTE_SESSION_ID is present only in version 2.4.3-p3
Table customer_entity column session_cutoff is present only in version 2.4.3-p3
Table customer_visitor column session_id length value is different. 2.4.3: "64", 2.4.3-p3: "1"
Table customer_visitor column session_id comment value is different. 2.4.3: "Session ID", 2.4.3-p3: "Deprecated: Session ID value no longer used"
Table customer_visitor column created_at is present only in version 2.4.3-p3
Table oauth_consumer column secret length value is different. 2.4.3: "32", 2.4.3-p3: "128"
Table oauth_token column secret length value is different. 2.4.3: "32", 2.4.3-p3: "128"
Table admin_user_session column session_id nullable value is different. 2.4.3: "false", 2.4.3-p3: "true"
Table admin_user_session column session_id length value is different. 2.4.3: "128", 2.4.3-p3: "1"
Table admin_user_session column session_id comment value is different. 2.4.3: "Session ID value", 2.4.3-p3: "Deprecated: Session ID value no longer used"

Total detected differences between version 2.4.3 and 2.4.3-p3: 11

使用core:code:changes命令

您可以比较当前的Adobe Commerce安装，以验证Adobe Commerce的核心代码是否已修改以实现自定义。 此命令仅显示核心修改的列表：

bin/uct core:code:changes <dir> <vanilla dir>

其中参数如下：

  • <dir>： Adobe Commerce安装目录。
  • <vanilla dir>： Adobe Commerce vanilla安装目录。

core:code:changes命令的可用选项：

命令
可用选项
core:code:changes
--help：返回所有可用的--help选项。
NOTE
最佳做法是将自定义代码排除在核心代码之外。 有关更多升级最佳实践，请参阅Adobe Commerce 2.4 升级指南。

Vanilla安装

vanilla ​安装是对特定发行版本的指定版本标记或分支的全新安装。

bin/uct core:code:changes命令检查系统中是否存在vanilla实例。 如果这是第一次使用vanilla安装，则会出现一个交互式命令行问题，提示您从Adobe Commerce存储库(https://repo.magento.com/)下载vanilla项目。

您可以运行带有--vanilla-dir选项的Upgrade Compatibility Tool命令，以指定Adobe Commerce vanilla安装目录。

有关详细信息，请参阅部署vanilla实例主题。

使用refactor命令

Upgrade Compatibility Tool能够自动修复缩减的问题：

  • 允许在不传递参数的情况下使用，但现在已弃用的函数。
  • 在Magento模板中使用$this。
  • 在专用方法中使用PHP关键字final。

为此，请执行refactor命令：

bin/uct refactor <dir>

其中，<dir>值是Adobe Commerce实例所在的目录。

refactor命令的可用选项：

命令
可用选项
refactor
--help：返回所有可用的--help选项。

使用graphql:compare命令

此命令为Upgrade Compatibility Tool提供选项，用于内嵌两个GraphQL端点并比较其架构，以查找它们之间的突破性更改和危险更改：

bin/uct graphql:compare <schema1> <schema2>

其中参数如下：

  • <schema1>：现有安装的终结点URL。
  • <schema2>： vanilla安装的端点URL。

graphql:compare命令的可用选项：

命令
可用选项
graphql:compare
--help：返回所有可用的--help选项。

使用list命令

要返回Upgrade Compatibility Tool可用命令的列表，请运行：

bin/uct list

使用help命令

要查看Upgrade Compatibility Tool命令的常规选项和帮助，请运行：

bin/uct --help

在命令行界面中为Upgrade Compatibility Tool返回一个包含所有可用help选项的列表：

- --raw             To output raw command list
- --format=FORMAT   The output format (txt, xml, json, or md) [default: "txt"]
- --short           To skip describing commands' arguments
- -h, --help            Display help for the given command. When no command is given display help for the list command
- -q, --quiet           Do not output any message
- -V, --version         Display this application version
- --ansi|--no-ansi  Force (or disable --no-ansi) ANSI output
- -n, --no-interaction  Do not ask any interactive question
- -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

运行特定命令时，可以将--help作为选项运行。 它返回指定命令的--help选项。

带--help选项的upgrade:check命令示例：

bin/uct upgrade:check --help

这会返回可以为upgrade:check命令运行的特定选项：

- -a, --current-version[=CURRENT-VERSION]: Current Adobe Commerce version, version of the Adobe Commerce installation will be used if omitted.
- -c, --coming-version[=COMING-VERSION]: Target Adobe Commerce version, latest released version of Adobe Commerce will be used if omitted. Provides a list of all available Adobe Commerce versions.
- --json-output-path[=JSON-OUTPUT-PATH]: Path of the file where the output will be exported in json format.
- --html-output-path[=HTML-OUTPUT-PATH]: Path of the file where the output will be exported in HTML format.
- --min-issue-level[=MIN-ISSUE-LEVEL]            Minimal issue level you want to see in the report (warning, error or critical). [default: "warning"]
- -i, --ignore-current-version-compatibility-issues  Ignore common issues for current and coming version
- --context=CONTEXT: Execution context. This option is for integration purposes and does not affect the execution result.
- -h, --help: Display help for that specific command. If no command is provided, `list` command is the default result.
- -q, --quiet: Do not output any messages while executing the command.
- -v, --version: Display application version.
- --ansi, --no-ansi: Enable ANSI output.
- -n, --no-interaction: Do not ask any interactive question while executing the command.
- -v, --vv, --vvv, --verbose: Increase verbosity of output communications. 1 for normal output, 2 for verbose output, and 3 for DEBUG output.

遵循Adobe Commerce最佳实践

优化结果

Upgrade Compatibility Tool提供包含结果的报告，其中默认包含项目中识别的所有问题。 您可以优化结果以重点关注为完成升级而必须修复的那些问题：

  • 当您只想在Upgrade Compatibility Tool报表中获取从当前版本更新到目标版本时引入的新问题时，请使用选项--ignore-current-version-compatibility-issues。
  • 通过添加--min-issue-level选项，此设置允许设置最低问题级别，以帮助仅排定升级中最重要的问题的优先级。
  • Upgrade Compatibility Tool至少需要2GB RAM才能运行。 建议使用此设置以避免由于内存不足限制导致的问题。 如果运行设置低memory_limit的upgrade:check命令，Upgrade Compatibility Tool会显示一个问题。
recommendation-more-help
83a60e0e-8849-4685-a8cd-c129ecd795ea