loan-pricing/.skills/fix-mysql-comments.md

修复MySQL数据库注释乱码

问题描述

MySQL数据库表和字段的中文注释显示为乱码，在Navicat等数据库管理工具中查看时出现 ?? 或其他乱码字符。

诊断方法

# 检查字段注释的十六进制编码
mysql -h <host> -P <port> -u <user> -p<password> "<database>" -e "
SELECT COLUMN_NAME, HEX(COLUMN_COMMENT) as comment_hex
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA='<database>' AND TABLE_NAME='<table_name>';
"

判断标准：

• ✅ 正确的UTF-8中文：以 E4-E9 开头（如 E698AF = 是）
• ❌ 错误编码：以 C3 开头（表示双重编码问题）

解决方案

方法1：创建UTF-8编码的SQL文件（推荐）

1. 创建SQL文件，确保保存为UTF-8编码：

-- fix_comments.sql
USE `<database>`;
SET NAMES utf8mb4;

ALTER TABLE `<table_name>` COMMENT = '正确的中文注释';

ALTER TABLE `<table_name>`
  MODIFY COLUMN `column1` varchar(50) DEFAULT NULL COMMENT '字段1中文注释',
  MODIFY COLUMN `column2` varchar(50) DEFAULT NULL COMMENT '字段2中文注释',
  -- ... 更多字段

2. 使用utf8mb4字符集执行：

mysql -h <host> -P <port> -u <user> -p<password> \
  --default-character-set=utf8mb4 "<database>" < fix_comments.sql

方法2：验证SQL文件编码

# 检查文件是否为UTF-8编码
file fix_comments.sql
# 应该输出: Unicode text, UTF-8 text

方法3：通过heredoc创建SQL文件（跨平台）

cat > fix_comments.sql << 'SQLEOF'
USE `your_database`;
SET NAMES utf8mb4;
ALTER TABLE your_table MODIFY COLUMN your_column varchar(10) DEFAULT NULL COMMENT '正确的中文注释';
SQLEOF

验证修复结果

# 查看表注释
mysql -h <host> -u <user> -p<password> "<database>" -e "
SELECT table_name, HEX(table_comment) as comment_hex
FROM information_schema.tables
WHERE table_schema='<database>' AND table_name='<table_name>';
"

# 查看字段注释
mysql -h <host> -u <user> -p<password> "<database>" -e "
SELECT COLUMN_NAME, COLUMN_COMMENT
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA='<database>' AND TABLE_NAME='<table_name>'
ORDER BY ORDINAL_POSITION;
"

# 检查是否还有乱码字段（C3开头）
mysql -h <host> -u <user> -p<password> "<database>" -e "
SELECT COUNT(*) as bad_comments
FROM information_schema.COLUMNS
WHERE TABLE_SCHEMA='<database>' AND TABLE_NAME='<table_name>'
AND HEX(COLUMN_COMMENT) REGEXP '^C3';
"

常见错误及原因

错误现象	原因	解决方案
C3A6CB9C... (C3开头)	双重编码：UTF-8被当作GBK处理后再转UTF-8	使用UTF-8文件 + utf8mb4执行
Windows命令行显示乱码	终端编码问题，数据库实际正确	用HEX()验证实际存储
SQL文件执行后仍乱码	文件未保存为UTF-8	用file命令检查编码

最佳实践

1. 所有SQL文件使用UTF-8编码保存
2. 始终使用 --default-character-set=utf8mb4 参数
3. 在SQL开头添加 SET NAMES utf8mb4;
4. 用HEX()验证而非肉眼判断
5. 批量修复时用脚本生成SQL文件

示例：批量生成修复SQL

#!/bin/bash
# 为指定表生成修复SQL

DB_NAME="your_database"
TABLE_NAME="your_table"

cat > fix_${TABLE_NAME}_comments.sql << SQLEOF
USE \`${DB_NAME}\`;
SET NAMES utf8mb4;

ALTER TABLE \`${TABLE_NAME}\`
  COMMENT = '表的中文名称';

ALTER TABLE \`${TABLE_NAME}\`
  MODIFY COLUMN \`id\` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  MODIFY COLUMN \`name\` varchar(100) DEFAULT NULL COMMENT '名称',
  -- 添加更多字段...
SQLEOF

# 执行修复
mysql -h localhost -u root -p${DB_PASS} \
  --default-character-set=utf8mb4 "${DB_NAME}" < fix_${TABLE_NAME}_comments.sql