Delphi FireDAC通过ODBC连接MySQL时中文乱码如何解决？

Question

在Delphi中使用FireDAC通过ODBC连接MySQL时，常出现中文插入/查询乱码（如显示为问号或方块），根本原因在于字符集未统一：MySQL服务端、ODBC驱动、FireDAC连接参数及客户端环境四者间编码不一致。典型表现为`TFDConnection.Params`未显式设置`CharacterSet=utf8`或`utf8mb4`，且ODBC数据源（DSN）中未勾选“Perform charset translation for character columns”或未指定`CHARSET=utf8mb4`；同时MySQL服务器的`character_set_server`、数据库/表的`COLLATION`若非`utf8mb4_unicode_ci`，亦会导致截断或转义失败。此外，FireDAC默认可能忽略ODBC层的编码配置，需强制在`FDConnection.Params`中添加`Charset=utf8mb4`并设置`Unicode=True`。忽略任一环节，均会引发中文存储异常或检索乱码——这并非单纯修改`TStringField`属性可解决，而是端到端的字符集协同问题。

Answer 1

```html

一、现象层：乱码的直观表现与典型错误模式

在Delphi FireDAC + ODBC + MySQL组合中，中文乱码常表现为：插入后显示为“???”、“”或方块符号；查询结果中汉字被截断（如“北京”变“北?”）；甚至SQL执行失败并抛出Incorrect string value错误。这些并非UI控件渲染问题，而是数据在传输链路中已被损坏。常见误操作包括：仅修改TStringField.Size、在TFDQuery.SQL.Text中硬编码SET NAMES utf8（FireDAC会忽略）、或依赖Windows系统区域设置自动转换——这在多语言服务器环境中必然失效。

二、链路层：四段式字符集协同模型（核心分析框架）

中文正确处理依赖以下四个环节严格对齐，任一断裂即引发乱码：

• MySQL服务端层：全局character_set_server=utf8mb4，数据库/表级COLLATE=utf8mb4_unicode_ci
• ODBC驱动层：DSN配置中必须勾选“Perform charset translation for character columns”，并在Additional Connection Settings中追加CHARSET=utf8mb4
• FireDAC连接层：TFDConnection.Params需显式设置Charset=utf8mb4和Unicode=True（True强制启用UTF-16↔UTF-8双向转换）
• 客户端环境层：Delphi项目启用Unicode支持（{$IFDEF UNICODE}），且操作系统区域设置不影响FireDAC行为（因其绕过ANSI API）

三、配置验证：关键参数诊断清单

层级	检查项	正确值示例	验证SQL/路径
MySQL服务端	character_set_server	utf8mb4	SHOW VARIABLES LIKE 'character_set_server';
MySQL库表	DEFAULT COLLATE	utf8mb4_unicode_ci	SHOW CREATE DATABASE mydb;
ODBC DSN	Advanced Settings → CHARSET	utf8mb4	Windows ODBC Data Source Administrator → Configure → Details
FireDAC	FDConnection.Params.Values['Charset']	utf8mb4	FDConnection.Params.Add('Charset=utf8mb4');

四、代码层：FireDAC连接参数的强制标准化写法

// ✅ 正确初始化（必须在Open前调用）
FDConnection.Params.Clear;
FDConnection.Params.Add('DriverID=ODBC');
FDConnection.Params.Add('Database=mydb');
FDConnection.Params.Add('User_Name=root');
FDConnection.Params.Add('Password=123');
FDConnection.Params.Add('Server=localhost');
FDConnection.Params.Add('Port=3306');
// 🔑 关键：显式声明字符集与Unicode模式
FDConnection.Params.Add('Charset=utf8mb4');   // 不可省略！
FDConnection.Params.Add('Unicode=True');       // 强制启用UTF-16 ↔ UTF-8转换
FDConnection.Params.Add('ExtendedMetadata=True');

// ⚠️ 禁止以下写法：
// FDConnection.Params.Add('CharacterSet=utf8'); // 错误：FireDAC不识别此Key
// FDConnection.Params.Add('UseUnicode=True');  // 错误：无效Key名

五、深度机制：FireDAC为何忽略ODBC的字符集配置？

FireDAC采用自主的字符集协商协议，其ODBC驱动（FDPhysODBCClientDriver）默认不继承ODBC Driver Manager的编码上下文。即使DSN中设置了CHARSET=utf8mb4，FireDAC仍以ANSI_CHARSET为默认解码器，导致从ODBC接收的UTF-8字节流被错误解释为Windows-1252。只有通过Charset参数显式注入，并配合Unicode=True触发内部TFDPhysODBCCommand.ConvertToUTF8转换管道，才能激活正确的双字节→四字节UTF-8映射。该机制在FireDAC源码FireDAC.Phys.ODBCWrapper.pas第1892行有明确实现。

六、排错流程图：结构化定位乱码根源

graph TD
  A[出现中文乱码] --> B{插入/查询均异常？}
  B -->|是| C[检查MySQL服务端字符集]
  B -->|仅插入异常| D[检查ODBC DSN CHARSET设置]
  B -->|仅查询异常| E[检查FireDAC Charset+Unicode参数]
  C --> F[character_set_server = utf8mb4?]
  F -->|否| G[修改my.cnf: [mysqld] character_set_server=utf8mb4]
  F -->|是| H[检查库/表COLLATION]
  H --> I[ALTER DATABASE mydb CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci]
  D --> J[ODBC DSN中是否勾选字符集转换？]
  J -->|否| K[重配DSN，启用“Perform charset translation”]
  E --> L[FDConnection.Params是否有Charset=utf8mb4且Unicode=True？]
  L -->|否| M[代码中强制Add这两项]

七、进阶陷阱：utf8 vs utf8mb4的致命差异

MySQL的utf8实为utf8mb3（最多3字节），无法存储Emoji、生僻汉字（如“𠜎”U+2070E）、数学符号等4字节UTF-8序列。若服务端设为utf8而客户端发送utf8mb4，MySQL将静默截断或报错1366: Incorrect string value。FireDAC中若设置Charset=utf8，虽能避免报错，但会导致4字节字符被替换为?。因此全栈必须统一使用utf8mb4，包括：MySQL配置、建表语句（CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci）、ODBC DSN、FireDAC Params——这是现代中文应用的底线要求。

八、验证脚本：一键检测全链路连通性

procedure TestChineseEncoding;
var
  Q: TFDQuery;
begin
  Q := TFDQuery.Create(nil);
  try
    Q.Connection := FDConnection;
    Q.SQL.Text := 'SELECT ''北京❤️测试'' AS msg, LENGTH(''北京❤️测试'') AS len_utf8';
    Q.Open;
    // ✅ 正确输出：msg='北京❤️测试', len_utf8=12（4汉字×3字节 + 1Emoji×4字节 = 12）
    // ❌ 错误输出：msg='北京??测试', len_utf8=10（Emoji被截断为2个?）
    ShowMessage(Q.FieldByName('msg').AsString);
  finally
    Q.Free;
  end;
end;

九、生产部署 checklist（含Windows/Linux双环境）

• ✅ MySQL：Linux下确认/etc/my.cnf含[client] default-character-set=utf8mb4与[mysqld] character-set-server=utf8mb4
• ✅ Windows：ODBC DSN必须使用MySQL ODBC 8.0 Unicode Driver（非ANSI版），且DSN类型为System DSN
• ✅ Delphi：项目选项→Options → Delphi Compiler → RTL Unicode Support必须启用
• ✅ 运行时：避免在TFDQuery.BeforeOpen中执行SET NAMES（FireDAC已内建字符集协商）
• ✅ 监控：部署后立即运行

  八

  节验证脚本，捕获真实字节长度

十、延伸思考：为什么TStringField属性修改无效？

根本原因在于：TStringField仅控制VCL控件的数据呈现逻辑（DisplayText、Text属性），而乱码发生在数据从MySQL经ODBC驱动、FireDAC网络层、内存缓冲区到字段值赋值的整个字节流阶段。当FireDAC从ODBC接收到损坏的UTF-8字节（如0xC0 0xA0被误读为Latin-1），TStringField.AsString拿到的已是错误Unicode码点，此时调整Size或FieldKind毫无意义。真正的修复点永远在链路起点——字符集声明的强制一致性。

```