乱码是排查里最容易被误判的一类问题：眼睛看到的是「锟斤拷」或者一串问号，第一反应往往是模型输出错了、接口坏了。其实绝大多数情况字节本身完全正确，只是中间某一层用错了表去读它。定位的思路只有一个——沿着请求走一遍，找出「谁写的字节」和「谁按什么规则读的」这两端在哪一步对不上。
根源只有一句话：字节和解码表对不上
中文在 UTF-8 里占三个字节，在 GBK 里占两个。同一段文字用不同规则编码，得到的字节序列完全不同；拿 A 规则写、用 B 规则读，就会读出一堆无意义的符号。乱码长得也有规律：出现「锟斤拷」通常是 UTF-8 字节被当成 GBK 解码后又转回 UTF-8；满屏问号多半是某个环节把无法映射的字符替换掉了；出现「ä¸Â」这类拉丁字母组合，则是 UTF-8 字节被当成了 Latin-1。
所以排查时不要盯着乱码本身猜，而是问三个问题：这段字节是哪个环节写出来的、它声明的字符集是什么、下游是用什么解码的。三个答案里只要有两个不一致，问题就找到了。
一个省时间的习惯：先用最小请求复现——一段固定的中文、一个固定的接口、不带任何业务逻辑。能在最小例子上复现，问题就在链路里；复现不了，才去怀疑某段特定数据。
服务端：把 Content-Type 声明清楚
接口返回 JSON 时，正确的响应头应当带上字符集，例如 Content-Type: application/json; charset=utf-8。少了 charset，很多客户端会退回系统默认编码，在英文环境里通常没事，在中文 Windows 上就按 GBK 解，乱码从此开始。返回 HTML 或纯文本时同理，头部声明和文件本身的实际编码必须一致，声明 UTF-8 却用 GBK 存盘，等于主动制造问题。
流式接口还有一层额外的坑：UTF-8 的一个汉字占三个字节，网络分片不保证按字符边界切，某一片的末尾很可能只有半个汉字。正确做法是在服务端按字符边界切分，或在客户端保留未完成的字节直到下一片到达再解码。直接把每片单独 decode 再拼接，就会在长回答里零星冒出乱码方块，且只在长文本时出现，极难复现。
客户端：按响应头解码，别按系统默认
很多 HTTP 库在拿不到 charset 时会用平台默认编码，这正是「本地好好的，换台机器就乱码」的根源。稳妥的写法是显式指定：拿到响应后先读 Content-Type 里的 charset，读不到就固定用 UTF-8 解码，不要留给运行环境去猜。读写文件、拼接 SQL、输出日志，凡是涉及文本的地方都统一成 UTF-8，链路里只要有一处例外就会漏。
如果确实要和旧系统对接 GBK 数据，在入口处一次性转码，转完立刻回到 UTF-8，不要让它以 GBK 的形态在系统里流动。接口统一走 https://api.aigcbreeze.cn/v1，请求体按 UTF-8 序列化即可；批量清洗历史数据时用 qwen3.8-flash 这类快模型先跑小样本，确认编码链路通了再全量跑，能省下大量重跑成本。
常见问题
流式返回里偶尔出现半个汉字，是模型的问题吗？
通常不是。模型输出的是完整文本，问题出在传输分片：一片的末尾切在了多字节字符中间。客户端保留残余字节、等下一片拼好再解码即可解决；如果只有个别客户端出现，优先查它的 decode 时机。
数据已经存进数据库才变乱码，还能救吗？
要看是哪一步错的。如果写入时已经是错的字节，原始信息可能已经丢失，只能靠业务数据反推；如果只是连接字符集没设对、库里的字节其实正确，改连接参数后重新读出来就能恢复。先取一条样本看十六进制，比反复试参数可靠得多。
同样的代码，为什么在 Windows 上就乱码？
因为 Windows 中文环境的默认代码页是 GBK，而服务器大多是 UTF-8。任何依赖「默认编码」的地方都会表现不同：读文件、控制台输出、子进程管道。把这些位置显式写成 UTF-8，跨平台差异就消失了。