Open WebUI 界面出现中文乱码,通常不是单一原因:需要先分辨是字符编码错乱还是字体缺字形。先建立两个观测指标:浏览器计算样式里的 font-family,以及接口响应的 Content-Type。瓶颈假设先放在 CSS 回退字体上;如果开发者工具里显示的是乱码字符,则把假设转向后端编码。下文按这个假设给出一轮排查顺序,每一步只改一个变量。
先确认乱码的类型和出现范围
打开浏览器开发者工具(F12),选中乱码元素,查看 Styles 面板实际生效的 font-family。如果出现的是方框或问号,说明字体缺字形;如果出现的是类似“汉嗔这种乱码,说明是编码问题。同时也看 Network 面板,检查该接口响应的 Content-Type 是否带 charset=utf-8,以及响应正文里的中文是否被正确编码。适用场景是本地部署的 Open WebUI,前端和后端都由同一服务提供。操作动作是使用 Chrome 或 Edge 的开发者工具,不要仅凭肉眼判断。验证方式是记录乱码元素的 HTML 和计算样式,再用 curl 请求同一接口,对比响应编码。风险边界在于:如果 Open WebUI 使用了反向代理,可能在中途改了响应头,需要在浏览器和命令行两端都确认。
语言包缺失和翻译不完整的处理顺序
Open WebUI 的界面语言选择在设置内,通常会把语言切换为中文。但前端语言包和内置素材若本身不完整,界面会退回英文,或部分文案变成硬编码字符串,这不属于字体问题。操作动作:先切换语言到简体中文,保存并强制刷新;再检查是否存在未汉化的相邻字段。若只有个别字段乱码,建议在 Open WebUI 的 i18n 路径下核对中文本地化文件是否缺失。风险边界:不要直接修改前端构建产物里的 locale JSON,项目升级后会被覆盖。如果必须修改,建议做本地补丁并确认升级策略。
替换默认字体:先做浏览器验证,再改统一字体栈
确认当前样式用的 font-family 不包含中文回退后,最直接的方式是写一段自定义 CSS,把 body 和输入框的字体栈改为 Noto Sans CJK SC, Microsoft YaHei, PingFang SC, sans-serif。适用场景是前端渲染缺字形。操作动作是进入管理后台或容器挂载的自定义 CSS 文件添加规则,保存后强制刷新(Ctrl+Shift+R)。验证方式:在开发者工具里查看计算样式是否变成新字体,再检查正文和输入框是否还有方框字。风险边界:Docker 部署的 Open WebUI 若没有把自定义 CSS 挂载出来,容器重建后会被重置;而且浏览器回退字体依赖操作系统里已安装的中文字体,服务端字体和浏览器字体是两回事。如果需要更底层,也可以在容器内安装中文字体并刷新系统字体缓存,但这属于宿主机或容器的环境问题,需要结合部署方式确认。
body, input, button, textarea {
font-family: Noto Sans CJK SC, Microsoft YaHei, PingFang SC, sans-serif;
}
这段 CSS 设置不是修复编码,只作用于字形回退,放在自定义 CSS 文件的最后即可。
编码问题需要查后端响应,而不是前端 CSS
如果开发者工具里看到的汉字本身已是乱码,说明数据在到达浏览器前就坏了,这时不要去调 CSS。操作动作:用 curl 直接请求 Open WebUI 的 API,查看响应头是否声明 charset=utf-8,请求体里是否含乱码。若有乱码,检查运行环境的 LANG 和 LC_ALL 变量,以及 Docker 镜像里的 locale 设置。以实际服务地址为准执行类似:
curl -I <服务地址>/api/<对应接口>
locale
第一行看响应头,第二行看当前终端语言环境。这些命令是通用的,具体返回值需要结合当前环境确认。风险边界:直接改容器内 locale 可能影响其他组件,建议先记录当前环境值再动手,不要把它当成唯一的修复手段。
一次只改一个变量:推荐的排查顺序
- 先切换语言为中文,保存并强制刷新,观察乱码范围是否有变化。
- 用开发者工具检查乱码元素的 font-family 和错误信息。
- 用 curl 或 Postman 请求对应接口,确认编码是否正常。
- 若缺字形,自定义 CSS 增加中文字体栈。
- 若编码错乱,检查运行环境变量,再考虑修改 locale。
每步之间只保留一个变量,避免把字体问题和编码问题混在一起。不要在同一轮测试中同时改 CSS 和重启容器,否则无法确认真正的失效点。