SillyTavern中文文档加载失败如何解决？

Question

问题：SillyTavern 中文文档加载失败，提示“Failed to load language file”或显示乱码。常见原因为语言文件路径错误、编码格式非 UTF-8 或前端未正确设置字符集。部分用户在本地部署时未将 `zh-CN.json` 放入正确目录，或服务器缓存旧文件导致加载失败。此外，浏览器未启用 CORS 策略也可能阻止资源读取。如何正确配置语言文件路径、确保 UTF-8 编码并清除缓存以解决中文文档加载异常？

Answer 1

一、问题现象与初步诊断

在本地部署 SillyTavern 时，部分用户反馈中文语言包加载失败，前端控制台报错“Failed to load language file”，或页面显示乱码（如 ）。此类问题通常出现在非英文操作系统或多语言支持场景下。常见触发条件包括：

• 未将 zh-CN.json 放置于正确的语言资源目录
• JSON 文件保存编码非 UTF-8
• Web 服务器未设置响应头 Content-Type: application/json; charset=utf-8
• 浏览器因 CORS 策略拒绝跨域读取本地文件
• CDN 或本地缓存导致旧版本语言文件被加载

二、路径配置检查与修复流程

确保语言文件位于正确路径是解决加载失败的第一步。SillyTavern 默认从 /public/locales/zh-CN/translation.json 或类似结构中读取语言资源。

部署方式	期望路径	实际检查命令
Docker 部署	/app/public/locales/zh-CN/translation.json	docker exec -it sillytavern ls /app/public/locales/zh-CN
Node.js 本地运行	./frontend/public/locales/zh-CN/zh-CN.json	find . -name "zh-CN.json"
Nginx 静态服务	/usr/share/nginx/html/locales/zh-CN/	curl http://localhost/locales/zh-CN/translation.json

三、文件编码验证与转换方法

即使路径正确，若 zh-CN.json 使用 GBK、ANSI 等非 UTF-8 编码，JavaScript 解析时会出现乱码或解析失败。推荐使用以下工具检测并转换编码：

# 检查当前编码
file -i zh-CN.json

# 使用 iconv 转换为 UTF-8
iconv -f GBK -t UTF-8 zh-CN.json -o zh-CN.json.utf8 && mv zh-CN.json.utf8 zh-CN.json

# 或使用 Python 快速验证
python3 -c "import json; print(json.load(open('zh-CN.json', 'r', encoding='utf-8')))"
    

四、HTTP 响应头与字符集设置

当通过 Web 服务器提供服务时，必须确保返回的 JSON 文件带有正确的 MIME 类型和字符集声明。以下是主流服务器配置示例：

• Nginx:

  location /locales/ {
      add_header Content-Type 'application/json; charset=utf-8';
      default_type application/json;
  }

• Express.js:

  app.use('/locales', (req, res, next) => {
    res.setHeader('Content-Type', 'application/json; charset=utf-8');
    next();
  });

五、CORS 策略与浏览器安全限制分析

现代浏览器对本地文件访问实施严格 CORS 控制。直接打开 index.html 可能导致 XMLHttpRequest 对 zh-CN.json 的请求被阻止。

graph TD A[用户打开 index.html] --> B{是否通过 HTTP 协议加载？} B -- 是 --> C[发送 XHR 请求获取 zh-CN.json] B -- 否 --> D[触发 CORS 错误] C --> E[成功加载语言包] D --> F[控制台报错 Failed to load language file]

六、缓存机制排查与清除策略

浏览器或反向代理可能缓存了错误的语言文件。建议执行以下步骤：

1. 强制刷新页面（Ctrl+Shift+R）
2. 清空浏览器缓存或使用无痕模式测试
3. 检查 Service Worker 是否注册并清除其缓存
4. 重启开发服务器以释放内存缓存
5. 在 Nginx 中禁用缓存用于调试：

   location ~* \.json$ {
       expires -1;
       add_header Cache-Control "no-store, no-cache";
   }

七、自动化检测脚本建议

为提升部署效率，可编写健康检查脚本自动验证语言文件状态：

#!/bin/bash
LANG_FILE="./public/locales/zh-CN/translation.json"

if [ ! -f "$LANG_FILE" ]; then
    echo "❌ 文件不存在: $LANG_FILE"
    exit 1
fi

ENCODING=$(file -bi "$LANG_FILE" | grep -o 'charset=[^;]*' | cut -d= -f2)
if [ "$ENCODING" != "utf-8" ]; then
    echo "⚠️ 编码警告: 当前为 $ENCODING，建议转为 utf-8"
fi

if ! jq empty "$LANG_FILE" 2>/dev/null; then
    echo "❌ JSON 格式无效，请检查语法"
    exit 1
fi

echo "✅ 语言文件就绪：路径正确、UTF-8 编码、JSON 有效"