FreeSql 中 MySQL 8.0 插入 Emoji 字符的解决方案

在使用 FreeSql 操作 MySQL 8.0 数据库时，开发者可能会遇到无法正确插入 Emoji 字符的问题，错误提示通常为"Incorrect string value"错误。本文将深入分析问题原因并提供完整的解决方案。

问题现象

当尝试向 MySQL 8.0 数据库插入包含 Emoji 字符的数据时，虽然数据库和表的字符集已设置为 utf8mb4，Navicat 等客户端工具可以正常插入，但通过 FreeSql 框架操作时仍会报错：

Incorrect string value: '\xF0\x9F\x8F\xA1' for column 'Title' at row 1

问题原因分析

1. 字符集不匹配：虽然数据库和表设置为 utf8mb4，但连接字符串中的字符集设置可能未生效
2. MySQL 驱动问题：不同版本的 MySQL 驱动对 utf8mb4 的支持存在差异
3. 多层级编码配置：MySQL 的字符集配置涉及多个层级（服务器、数据库、表、列、连接）

完整解决方案

1. 检查并修改数据库配置

确保数据库、表和列的字符集都设置为 utf8mb4：

-- 修改数据库字符集
ALTER DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 修改表字符集
ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 检查列的字符集
SHOW FULL COLUMNS FROM table_name;

2. 使用正确的连接字符串

在 FreeSql 连接字符串中明确指定字符集：

"Server=localhost;Port=3306;Database=test;Uid=root;Pwd=123456;Charset=utf8mb4;"

注意：必须使用 utf8mb4 而非 utf8。

3. 更换 MySQL 驱动

FreeSql 提供了两种 MySQL 驱动实现：

1. FreeSql.Provider.MySql（基于官方 MySql.Data）
2. FreeSql.Provider.MySqlConnector（基于 MySqlConnector）

推荐使用 MySqlConnector 实现，它对 utf8mb4 的支持更好：

# 卸载原有驱动
dotnet remove package FreeSql.Provider.MySql

# 安装 MySqlConnector 驱动
dotnet add package FreeSql.Provider.MySqlConnector

4. 验证字符集设置

可以通过以下 SQL 查询验证当前字符集设置：

SHOW VARIABLES LIKE 'character_set%';
SHOW VARIABLES LIKE 'collation%';

确保以下变量值为 utf8mb4：

• character_set_client
• character_set_connection
• character_set_database
• character_set_results
• character_set_server

深入理解

MySQL 的 utf8 字符集实际上只支持最多 3 字节的字符，而 Emoji 等特殊字符需要 4 字节编码，因此必须使用 utf8mb4。utf8mb4 是 MySQL 对标准 UTF-8 的实现，完全支持 4 字节字符。

FreeSql 作为 ORM 框架，其字符编码行为依赖于底层 MySQL 驱动。MySqlConnector 驱动相比官方驱动在字符集处理上更为完善，特别是在处理 4 字节 UTF-8 字符时表现更好。

总结

解决 FreeSql 中 MySQL 插入 Emoji 字符的问题需要多方面的配置：

1. 确保数据库各级字符集设置为 utf8mb4
2. 连接字符串明确指定 utf8mb4
3. 使用更可靠的 MySqlConnector 驱动实现

通过以上步骤，可以确保 FreeSql 能够正确处理包含 Emoji 在内的所有 UTF-8 字符。