Laravel存储外文至name字段触发UTF-8编码错误问题排查

可能原因 #

• 字段结构差异：name和username的字段类型、长度或NULL属性不一致，导致写入外文时截断产生无效UTF-8字符。
• 模型隐式属性处理：User模型或其引入的Trait、父类中存在针对name字段的访问器/修改器，在序列化或读取时损坏了UTF-8编码。
• 编码配置不匹配：数据库全局排序规则为utf8mb4_0900_ai_ci，字段排序规则为utf8_unicode_ci，而Laravel数据库连接配置的collation为utf8mb4_unicode_ci，三者不一致导致编码转换冲突。
• 写入阶段编码错误：写入name字段时存在额外的字符串处理逻辑（如错误转码、过滤），破坏了原始UTF-8内容。

排查与解决步骤 #

1. 核对数据库字段结构
   执行SQL查询确认两个字段的定义完全一致：

   SHOW COLUMNS FROM users LIKE 'name';
   SHOW COLUMNS FROM users LIKE 'username';
   

   确保两者的类型（如varchar(255)）、长度、是否允许NULL、字符集完全相同。

2. 排查模型属性处理逻辑

   • 检查User模型中是否存在getNameAttribute访问器或setNameAttribute修改器，这类方法可能在处理字段值时导致编码损坏。
   • 查看模型引入的Trait（如第三方包提供的）或父类Authenticatable中是否有针对name字段的隐式处理。
   • 临时在查询中直接获取原始值验证：

     $user = User::withTrashed()->notAdmin()->first();
     var_dump($user->getRawOriginal('name')); // 若不报错，说明是序列化/访问器导致的问题
     

3. 统一编码配置
   修改config/database.php中的MySQL连接配置，使其与数据库全局排序规则一致：

   'mysql' => [
       'charset' => 'utf8mb4',
       'collation' => 'utf8mb4_0900_ai_ci', // 和数据库全局规则对齐
       'options' => extension_loaded('pdo_mysql') ? array_filter([
           PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),
       ]) : [],
   ]
   

   修改后清除配置缓存：php artisan config:clear

4. 验证数据库中原始数据
   用十六进制查看name字段的原始内容，确认是否为有效UTF-8：

   SELECT id, name, HEX(name) FROM users WHERE name LIKE '%外文内容%';
   

   对比username字段的十六进制值，若name的HEX值存在无效UTF-8的特征（如截断的多字节字符），说明写入时已损坏。

5. 检查写入逻辑
   查看创建/更新用户的代码，确认是否对name字段做了额外处理（如mb_substr、iconv等），若存在错误的编码转换，修正为正确的UTF-8处理逻辑。

内容的提问来源于stack exchange，提问作者danish-khan-I