用途说明：
✔ 接口返回乱码
✔ 返回值看不懂
✔ 状态码正常但内容异常
✔ 快速判断“接口问题 or 自己问题”
一、最常见 API 返回编码对照表
| 返回现象 | 实际编码 | 常见来源 | 正确处理方式 |
|---|---|---|---|
| 正常中文 | UTF-8 | 新接口 / 国际 API | 直接使用 |
| 乱码（���） | UTF-8 被当成 GBK | 页面/文件编码不一致 | 统一 UTF-8 |
| 乱码（锟斤拷） | GBK 被当成 UTF-8 | 国内老接口 | mb_convert_encoding |
| 中文全问号 | ISO-8859-1 | 历史系统 | 转 UTF-8 |
| 显示正常但 JSON 解析失败 | UTF-8 + BOM | 编辑器坑 | 去 BOM |
| 看起来像乱码 | gzip 压缩 | 没解压 | CURLOPT_ENCODING => '' |
二、Header 与真实编码不一致（高频坑）
| Header 声明 | 实际内容 | 现象 | 正确做法 |
|---|---|---|---|
| UTF-8 | GBK | 中文乱码 | 强制转码 |
| UTF-8 | UTF-8+BOM | JSON 报错 | 去 BOM |
| 未声明 | GBK | 浏览器乱猜 | 手动转码 |
| text/html | JSON | 解析失败 | 自己 json_decode |
📌 结论一句话：Header 只能参考，不能迷信。
三、PHP / cURL 常见错误 & 根本原因速查
| 错误表现 | 真正原因 | 排查关键点 |
|---|---|---|
| 返回乱码 | 编码不一致 | 看 Header + 实际编码 |
| 空字符串 | 超时 / 被拦截 | curl_error |
| false | SSL / 证书 | CURLOPT_SSL_VERIFYPEER |
| JSON 解析失败 | BOM / 非 UTF-8 | json_last_error() |
| 看着是乱码 | gzip 压缩 | CURLOPT_ENCODING |
| 只在服务器乱码 | CLI / Web 编码不同 | 输出环境 |
四、常见 HTTP 状态码 + 真相翻译
| 状态码 | 表面含义 | 实际你该查什么 |
|---|---|---|
| 200 | 成功 | 内容是否被转码 |
| 400 | 参数错误 | 编码 / 参数格式 |
| 401 | 未授权 | token / header |
| 403 | 被拒绝 | IP / UA / 频率 |
| 404 | 不存在 | 接口地址 |
| 500 | 服务器错误 | 多半你传错了 |
📌 200 ≠ 没问题，内容才是关键。
五、乱码排查「黄金 5 步法」
1️⃣ 用 curl / Postman 看原始返回
2️⃣ 看 Header 的 charset
3️⃣ 用 mb_detect_encoding 判断
4️⃣ 必要时只转一次码
5️⃣ 最后再 echo 输出
六、推荐的“安全转码写法”
$encoding = mb_detect_encoding($result, ['UTF-8','GBK','GB2312'], true);
if ($encoding && $encoding !== 'UTF-8') {
$result = mb_convert_encoding($result, 'UTF-8', $encoding);
}
七、新手最容易犯的 5 个错误
❌ 不看 Header
❌ 连续转码
❌ 编码没确认就 json_decode
❌ 文件本身是 GBK
❌ 把 gzip 当乱码
API 乱码不是技术玄学，
而是：
你用错了“翻译规则”。
