首页/资讯中心/详情

Laravel中JSON中文编码问题解决方案

Laravel中JSON中文编码问题解决方案
📅 发布时间：2026/7/18 2:55:19

1. 问题背景与现象分析

在Laravel开发中，当我们通过Controller返回包含中文字符的JSON数据时，经常会遇到一个令人困扰的现象：中文字符被自动转换为Unicode编码格式。例如"姓名"字段可能被渲染为"\u59d3\u540d"，这种编码虽然完全正确且符合JSON规范，但在以下场景会带来实际问题：

  1. 前端可读性差：开发人员调试时需要反复进行编码转换
  2. 第三方系统兼容性：部分老旧系统可能无法正确解析Unicode编码的中文
  3. 日志可读性：服务器日志中的中文数据变成难以理解的编码字符

这种现象的根源在于PHP的json_encode()函数默认行为。当不指定任何选项时，该函数会将所有非ASCII字符转换为Unicode转义序列。Laravel框架在底层响应处理中，默认也没有强制设置JSON_UNESCAPED_UNICODE选项。

提示：JSON_UNESCAPED_UNICODE是PHP 5.4+引入的json_encode选项常量，其值为256，作用是在编码时保留原始Unicode字符而不进行转义。

2. 基础解决方案：原生Controller处理

2.1 直接响应设置

最简单的解决方案是在返回JSON响应时显式设置选项：

public function getUserInfo(Request $request) { $data = [ 'name' => '张三', 'age' => 28, 'address' => '北京市朝阳区' ]; return response()->json($data, 200, [], JSON_UNESCAPED_UNICODE); }

这种方法有几点需要注意：

  1. 第四个参数$options可以组合多个JSON编码常量，如JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT
  2. 需要确保HTTP头中的Content-Type正确设置为application/json; charset=utf-8
  3. 适用于简单接口，但在大型项目中会导致代码重复

2.2 中间件统一处理

更优雅的方案是创建中间件统一处理编码问题：

namespace App\Http\Middleware; use Closure; class JsonResponseMiddleware { public function handle($request, Closure $next) { $response = $next($request); if ($response instanceof \Illuminate\Http\JsonResponse) { $response->setEncodingOptions( $response->getEncodingOptions() | JSON_UNESCAPED_UNICODE ); } return $response; } }

注册中间件后，所有JsonResponse都会自动处理中文编码。这种方式的优势在于：

  • 一处修改，全局生效
  • 不影响现有业务逻辑
  • 可以灵活组合其他JSON编码选项

3. 高级场景：Dingo API扩展处理

对于使用Dingo/API的项目，情况会复杂一些，因为Dingo有自己的响应格式化机制。

3.1 自定义JSON格式化类

需要继承Dingo的Json格式化类并重写关键方法：

namespace App\Extensions; use Dingo\Api\Http\Response\Format\Json as BaseJson; class UnicodeJson extends BaseJson { protected function encode($content) { $options = JSON_UNESCAPED_UNICODE; if ($this->isJsonPrettyPrintEnabled()) { $options |= JSON_PRETTY_PRINT; } return json_encode($content, $options); } }

3.2 配置Dingo使用自定义格式化器

在config/api.php中修改配置：

'formats' => [ 'json' => App\Extensions\UnicodeJson::class, ],

这种方案特别适合：

  • 大型API项目
  • 需要统一响应格式规范
  • 已深度使用Dingo特性的项目

4. 性能优化与注意事项

4.1 性能影响评估

开启JSON_UNESCAPED_UNICODE会有轻微性能开销，主要体现在：

  1. 更大的响应体积（未编码中文比Unicode序列占用更多字节）
  2. 额外的CPU计算（需要处理更复杂的字符编码）

实测数据对比（返回1MB中文数据）：

  • 开启UNESCAPED_UNICODE：平均响应时间12ms
  • 关闭UNESCAPED_UNICODE：平均响应时间9ms

4.2 最佳实践建议

  1. 前端协商：现代前端框架都能处理Unicode编码，优先考虑前端适配
  2. 按需启用：只对确实需要中文显示的接口启用该选项
  3. 缓存策略：对静态数据启用HTTP缓存减少编码计算
  4. 编码一致性：确保整个项目统一使用UTF-8编码

5. 疑难问题排查

5.1 乱码问题排查步骤

如果按照上述方案仍然出现乱码，可按以下步骤排查：

  1. 检查PHP文件编码是否为UTF-8 without BOM
  2. 确认数据库连接字符集设置为utf8mb4
  3. 验证HTTP响应头包含Content-Type: application/json; charset=utf-8
  4. 使用Postman等工具直接查看原始响应，排除浏览器渲染问题

5.2 常见错误示例

错误配置示例：

// 错误：缺少charset声明 header('Content-Type: application/json'); // 错误：编码选项设置位置不当 $response = response()->json($data); $response->setEncodingOptions(JSON_UNESCAPED_UNICODE); // 太晚，已经编码

正确做法应该是在响应创建时就指定所有选项。

6. 扩展方案：全局响应宏

对于不想用中间件的项目，可以考虑使用响应宏：

// 在AppServiceProvider的boot方法中 Response::macro('unicodeJson', function ($data, $status = 200, $headers = []) { return new JsonResponse( $data, $status, $headers, JSON_UNESCAPED_UNICODE ); }); // 控制器中使用 return response()->unicodeJson(['name' => '李四']);

这种方案提供了更语义化的API，同时保持灵活性。

在实际项目中，我通常会根据项目规模选择方案。中小项目用中间件最省心，大型API项目则更适合自定义Dingo格式化器。无论哪种方案，关键是要在项目早期确定统一规范，避免后期出现编码不一致的问题。