必须用mysqlsh的util.checkforserverupgrade()，因mysqlcheck仅校验表结构损坏，无法识别utf8mb3字符集、rank等保留字冲突、caching_sha2_password认证插件不兼容等语义级问题。

必须用 mysqlsh 的 util.checkForServerUpgrade()，其他工具（包括 mysqlcheck --check-upgrade）对 utf8mb3、保留字、认证插件等语义级问题完全无感，不能替代。

为什么不能用 mysqlcheck 做升级兼容性检查

mysqlcheck --check-upgrade 只校验表文件结构是否损坏、索引页是否断裂、MyISAM 表定义是否匹配，属于存储引擎层的“物理体检”。它不解析 SQL 语义，也不比对版本行为差异：

• 列名是 rank 或 window？升级后所有 SELECT rank FROM t 全挂，mysqlcheck 不报
• 用户认证插件仍是 caching_sha2_password，但客户端驱动太老连不上？mysqlcheck 不查认证链
• 表字符集还是 utf8（即 utf8mb3），8.0 虽兼容但已废弃并警告？mysqlcheck 不扫描字符集定义
• 配置里还开着 query_cache_type=1？8.0 启动直接失败，mysqlcheck 视而不见

运行 util.checkForServerUpgrade() 的硬性前提

这个函数不是装个 mysql-shell 就能跑通的，缺一不可：

• 必须用 MySQL Shell 8.0.33 或更高版本（低版本如 5.7 或 6.0 会报 TypeError: util has no attribute 'checkForServerUpgrade'）
• 必须用目标版本对应的 mysqlsh 二进制连接（例如要升到 8.0.42，就得用 mysql-shell-8.0.42）
• 连接必须走本地 socket：mysqlsh -uroot -p -S /tmp/mysql.sock，避免 SSH 隧道或代理干扰
• 账号需具备 SUPER 权限和所有库的 SELECT 权限（root 最稳）
• 若启用组复制，必须先执行 STOP GROUP_REPLICATION，否则报 ER_GROUP_REPLICATION_PLUGIN_IS_ON

关键参数怎么传才有效

默认调用会扫描全部库和配置，生产环境必须加过滤，否则误报多、耗时长。核心 config 对象字段：

MySQL

编写正确的MySQL查询，避免字符集、索引和锁方面的常见陷阱。

下载

• targetVersion: "8.0.42"：写具体小版本，别写 "8.0"——不同 8.0.x 对 NO_ZERO_DATE、utf8mb3 的处理有差异
• excludeSchemas: ["test", "tmp_log", "archive_2023"]：传数组，跳过测试库、日志库、归档库
• outputFormat: "JSON"：比默认表格输出更易解析，方便配合 jq 自动提取 ERROR
• configPath: "/etc/my.cnf"：让工具校验配置文件里是否含废弃参数（如 query_cache_type）

完整命令示例：
mysqlsh --uri root@localhost:3306 --sql -e "util.checkForServerUpgrade({targetVersion: '8.0.42', excludeSchemas: ['test_db'], outputFormat: 'JSON', configPath: '/etc/my.cnf'});"

报告里哪些 ERROR 必须人工处理

输出分 ERROR/WARNING/NOTE 三级，只有 ERROR 是阻断项，不修完就不能启动 8.0：

• ERROR: Usage of utf8mb3 charset → 批量执行 ALTER TABLE tbl CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci
• ERROR: Column name 'rank' is a reserved keyword → 列名必须改（如 col_rank），不能只加反引号包住（后者在某些语法下仍会出错）
• ERROR: Plugin 'query_cache' is not available → 删除 my.cnf 中的 query_cache_type 和 query_cache_size
• ERROR: Authentication plugin 'caching_sha2_password' is not supported by client → 检查客户端驱动版本（如 mysql-connector-java ≥ 8.0.13），或临时切回 mysql_native_password

真正拦路的是这些 ERROR 条目，summary 段末的 overallStatus 必须为 OK。很多人忽略 configPath 参数导致配置项漏检，或者用错 mysqlsh 版本得出虚假“干净”报告——这两点最容易被跳过。