拿到这个问题,我会先确认乱码出现的范围。是浏览器里整个页面都乱码,还是只有模型回复的那一段乱码?这决定了后面从哪一层开始查。很多本地模型项目加载页是正常的,问题只在输出区域,这种情况通常不用去动网页本身的模板。
先区分乱码出现的位置
先区分乱码出现的位置。如果页面上的中文按钮或提示正常,只有模型回复内容乱码,说明浏览器显示层没问题,问题多出在模型输出后的编码传递链路上;反之,如果页面整体的中文都乱码,优先检查网页自身的字符集设置。可以通过浏览器的“查看编码”功能临时切换为 UTF-8 或 GBK,观察哪个能恢复,这样能快速缩小范围。
这个临时切换只是诊断动作,不会改变服务器配置。如果在切换后页面恢复,说明响应头里没有明确声明 charset,或者声明的编码与实际字节不一致;如果切换后依然乱码,就要继续往下追。
优先检查 HTTP 响应头
对于本地模型服务,最常见的修复方式是确保 HTTP 响应头明确声明字符集。在 FastAPI 中,返回 JSON 时指定 `media_type="application/json; charset=utf-8"` 或使用 `JSONResponse` 并设置 `headers`;在 Flask 中,可以在响应对象上调用 `response.headers["Content-Type"] = "text/html; charset=utf-8"`。同时,在 HTML 模板的 `` 里添加 `` 作为兜底。
这里的关键是让浏览器不再猜测编码。响应头的优先级比 HTML 内 meta 高,所以两个位置都写上,可以覆盖绝大多数情况。注意,如果是 API 接口,别忘了 JSON 响应也是文本,同样需要 charset 声明。
检查后端代码与运行环境编码
响应头修好后,如果乱码仍存在,就轮到后端代码和运行环境。Python 脚本文件顶部没有声明编码,或者运行环境默认不是 UTF-8,都可能让字符串在内存里已经是错误字节。常见做法是在源码头部写清 coding 声明,并在启动服务前设置 PYTHONIOENCODING。可以用 `locale` 命令查看当前语言环境,确认 LANG 是否包含 UTF-8。
这里要区分两个层面:代码文件保存时的字节编码,以及 Python 解释器运行时对字符串的处理编码。前者靠文件头声明,后者靠环境变量。只改文件不改环境,或者只改环境不管文件,都可能留下隐患。
流式输出和反向代理是重灾区
有一种情况很容易误判:页面刷新几次,有时正常有时乱码。这大多不是随机故障,而是流式输出没有统一编码。模型通过 SSE 逐段返回文本时,每个 chunk 都必须保持同样的字符集;如果中间有一层代理擅自按 ISO-8859-1 解码,中文边界就断了。Nginx 做反向代理时,proxy_pass 之后可能需要补充与编码相关的请求头设置,并确认代理没有强制修改 Content-Type。
判断方法很简单:分别直连后端服务和通过代理访问,对比返回内容是否一致。如果直连正常、经代理乱码,问题就在代理层;如果直连也乱码,继续查后端和前端解码逻辑。
用 curl 和开发者工具验证
修改完配置后,不要只看页面。建议先用 curl 确认响应头:
curl -I http://127.0.0.1:8000/ 看返回的 Content-Type 是否带 charset=utf-8。对于流式接口,可以用 curl -N 观察逐段输出,或者直接看浏览器开发者工具“网络”面板里的响应头。确认无误后,强制刷新页面(Ctrl+F5),再测一句包含中文引号和 emoji 的输入,检查整条链路。如果后端不方便改,前端也可以用 TextDecoder 手动按 UTF-8 解码。但要注意避免双重解码,比如先用 fetch 得到了文本,又按字节解码一次,反而会更乱。这种情况下,优先推动后端修正响应头。
回滚与风险边界
最后提醒一点:不要直接修改整个操作系统的默认代码页到 UTF-8,尤其在 Windows 上会导致现有程序乱码。更稳妥的做法是在启动服务的终端里执行 `chcp 65001`,只改变当前控制台的编码。对于 Docker 容器,不要依赖宿主机的 locale,而是在 Dockerfile 中安装 `locales` 并设置 `ENV LANG=C.UTF-8`,这样容器内的 Python 和其他组件才能正确输出中文。
这些改动都限制在服务启动范围内,回滚时只需要还原启动脚本或 Dockerfile 配置。如果之前手动改过系统 locale,建议先记下原始值再动,确认服务恢复正常后,再决定是否保留这个改法。