JSON配置文件的UTF-8 BOM编码陷阱

前端Baymax2026-07-14 9:52

JSON 配置文件的 UTF-8 BOM 编码陷阱------技术复盘

问题现象

autoglm-browser-service 启动后读取 config.json 静默失败，服务运行正常但所有浏览器相关功能无法使用，日志里没有任何明显错误。

排查过程

第一反应：配置文件路径错误？ → 检查后发现路径正确，文件存在
怀疑 JSON 格式不对 → 用 VSCode/在线 JSON 校验器检查，格式完全合法
怀疑权限问题 → 检查文件权限，当前用户完全可读可写
用 Hex 编辑器查看文件 → 发现文件以 EF BB BF（UTF-8 BOM）开头
对比正常工作的配置文件 → 没有 BOM 头

根因

Windows 下 PowerShell 的 Set-Content -Encoding UTF8 默认会写入 UTF-8 BOM （字节序标记 0xEFBBBF）。autoglm-browser-service 的 JSON 解析器（Go/Python 极简实现）没有处理 BOM，直接按纯文本读，导致第一个字符是 BOM 而非 {，JSON 解析失败，且因为默认静默 fail 而不报错。

解决方案

powershell 复制代码

# ❌ 错误（默认带 BOM）
$json | Set-Content "config.json" -Encoding UTF8

# ✅ 正确（无 BOM）
$json | Out-File -FilePath "config.json" -Encoding ascii -NoNewline

核心原则：Windows 环境写入 JSON 配置时强制使用 ASCII 编码（无 BOM），确保跨语言/跨平台兼容。

复盘总结

BOM 是 Windows 生态的老坑：历史原因 UTF-8 BOM 在 Windows 上很常见，但绝大多数非微软系的工具（Go、Python、Node）不处理 BOM
静默失败是最坏的失败：如果解析器能报一个明确的 "unexpected BOM" 错误，排查时间从 2 小时缩短到 2 分钟
教训：跨语言系统集成时，文本文件的编码约定必须显式声明，不能依赖平台的默认行为
排查技巧：遇到"文件明明存在且内容正确就是不生效"的诡异问题时，第一时间用 Hex 编辑器看原始字节，远比肉眼检查有用

积累 +1。每天一个小知识点，一年后就是 365 个。💪

#技术复盘 #UTF-8 #BOM #编码陷阱 #PowerShell #JSON