Alembic中Unicode字符无法正常工作的问题排查

核心原因分析 #

• 连接字符集不兼容：你在create_engine里用了utf8字符集，但数据库配置的是utf8mb4。MySQL的utf8仅支持3字节Unicode字符，像Nguyễn里的ế属于4字节字符，用utf8连接读取时会被截断替换成问号；而Johñ里的ñ是3字节字符，所以能正常显示。Flask应用应该是用了utf8mb4的连接配置，所以读取正常。
• Alembic连接配置不一致：调试日志显示检测到utf8_bin排序规则，说明迁移脚本里的数据库连接没有继承Flask应用的正确配置，而是用了默认或错误的字符集参数，导致连接层面就出现了字符编码转换错误。
• 日志编码的次要影响：日志里出现的"\xa0"是不间断空格的转义表示，属于日志输出时的编码处理问题，不是核心的问号问题，但也可以通过调整日志编码优化。

解决步骤 #

1. 修正数据库连接字符集
   把create_engine的URL中的charset=utf8改成charset=utf8mb4，示例：

   engine = create_engine('mysql+pymysql://username:password@host/database?charset=utf8mb4')
   

2. 统一Alembic与Flask的连接配置
   在Alembic的env.py中，不要单独创建新的engine，直接导入Flask应用中已经配置好的数据库连接，避免配置不一致：

   # env.py中修改如下
   from your_flask_app import db
   target_metadata = db.metadata
   connectable = db.engine
   

3. 验证连接字符集
   在迁移脚本中添加调试代码，确认连接的字符集是否正确：

   with engine.connect() as conn:
       result = conn.execute("SHOW VARIABLES LIKE 'character_set_connection'")
       print("当前连接字符集:", result.fetchone())
   

   正常输出应该是('character_set_connection', 'utf8mb4')。
4. 调整日志编码
   如果日志仍有转义问题，可在Alembic的配置文件或迁移脚本中设置日志的编码为utf-8：

   import logging
   logging.basicConfig(encoding='utf-8')
   

内容的提问来源于stack exchange，提问作者Charles L.