FreeSql 中 MySQL 8.0 处理 Emoji 字符的完整解决方案

问题背景

在使用 FreeSql 操作 MySQL 8.0.28 数据库时，开发者遇到了无法正确插入 Emoji 字符的问题。虽然数据库和表都已设置为 utf8mb4 字符集，Navicat 工具可以正常插入 Emoji，但通过 FreeSql 框架操作时却报错："Incorrect string value: '\xF0\x9F\x8F\xA1' for column 'Title' at row 1"。

问题分析

这个问题的根源在于 MySQL 对 Unicode 字符的支持层级。虽然 MySQL 8.0 默认使用 utf8mb4 字符集，但要正确处理 Emoji 等四字节 UTF-8 字符，需要确保以下几个环节都配置正确：

1. 数据库级别的字符集设置
2. 表级别的字符集设置
3. 列级别的字符集设置
4. 客户端连接时的字符集协商
5. 连接驱动对字符集的处理

完整解决方案

1. 检查并修改数据库字符集

首先确保数据库本身使用 utf8mb4 字符集：

ALTER DATABASE 数据库名称 CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 检查并修改表字符集

确保目标表也使用 utf8mb4 字符集：

ALTER TABLE 表名称 CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 检查列级别的字符集

确认需要存储 Emoji 的列使用正确的字符集：

ALTER TABLE 表名称 MODIFY 列名称 VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. 连接字符串配置

在 FreeSql 的连接字符串中，必须明确指定字符集：

Server=服务器地址;Port=3306;Database=数据库名;Uid=用户名;Pwd=密码;Charset=utf8mb4;

5. 使用正确的 MySQL 驱动

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

1. FreeSql.Provider.MySql - 基于官方 MySql.Data 驱动
2. FreeSql.Provider.MySqlConnector - 基于 MySqlConnector 驱动

推荐使用 MySqlConnector 驱动，它对字符集处理更加可靠：

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

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

深入理解

MySQL 中 utf8 和 utf8mb4 的区别：

• utf8: MySQL 中的"utf8"实际上是 UTF-8 的一个子集，只支持最多三个字节的字符（基本多文种平面）
• utf8mb4: 完整的 UTF-8 实现，支持四字节字符（如 Emoji、某些罕见汉字等）

FreeSql 在处理字符集时，会依赖底层 MySQL 驱动对连接字符集的协商。MySqlConnector 驱动在这方面表现更加稳定，能更好地处理字符集转换。

最佳实践建议

1. 新建 MySQL 8.0+ 数据库时，建议全局设置为 utf8mb4
2. 对于需要国际化的应用，统一使用 utf8mb4_unicode_ci 排序规则
3. 优先选择 MySqlConnector 驱动
4. 在连接字符串中显式声明 Charset=utf8mb4
5. 定期检查表和列的字符集设置

通过以上完整配置，FreeSql 将能够正确处理所有 Unicode 字符，包括 Emoji 和各种特殊符号。