【Bug已解决】Settings.json parse error / Invalid JSON configuration — Claude Code 配置文件解析错误解决方案1. 问题描述Claude Code 启动时或运行中报配置文件解析错误$ claude Error: Failed to parse settings.json SyntaxError: Unexpected token in JSON at position 45 at JSON.parse (anonymous) # 或配置不生效 $ cat ~/.claude/settings.json {model: sonnet, streaming: true} # 缺少引号 $ claude Warning: Invalid settings.json, using defaults # 配置被忽略使用默认值 # 或 CC Switch 写入后格式损坏 $ cat ~/.claude/settings.json {apiKey: sk-xxx,model:sonnet,} # 尾部逗号 $ claude Error: Unexpected token } in JSON at position 52这个问题在以下场景中特别常见手动编辑 settings.json 时 JSON 格式错误CC Switch 等工具写入非标准 JSON配置文件包含注释JSON 不支持注释尾部逗号单引号代替双引号文件编码问题非 UTF-82. 原因分析核心原理拆解settings.json 文件 → JSON.parse() 解析 ↓ 格式不符合 JSON 标准引号/逗号/注释 ↓ 解析失败 → 使用默认配置或报错原因分类表原因分类具体表现占比缺少引号key 或 value 未用双引号约 30%尾部逗号最后一个属性后有逗号约 25%单引号使用 代替 约 20%JSON 注释JSON 不支持 // 或 /* */约 15%CC Switch 损坏工具写入格式不标准约 5%编码问题非 UTF-8约 5%3. 解决方案方案一使用 JSON 验证工具修复最推荐# 步骤 1验证 JSON 格式 python3 -m json.tool ~/.claude/settings.json # 会指出具体错误位置 # 步骤 2或使用 node 验证 node -e JSON.parse(require(fs).readFileSync(~/.claude/settings.json,utf8)) # 步骤 3或使用 jq 验证 cat ~/.claude/settings.json | jq . # 如果报错说明 JSON 格式有问题 # 步骤 4根据错误信息修复方案二重写正确的 settings.json# 步骤 1备份损坏的文件 cp ~/.claude/settings.json ~/.claude/settings.json.bak # 步骤 2重写正确的 JSON cat ~/.claude/settings.json EOF { model: claude-sonnet-4-20250514, streaming: true, autoUpdate: true, allowedTools: [ Read, Write, Edit, Bash, Search ], maxConsecutiveToolCalls: 10 } EOF # 步骤 3验证 python3 -m json.tool ~/.claude/settings.json # 不报错说明格式正确 # 步骤 4重启 Claude Code claude方案三修复常见的 JSON 格式错误# 错误 1: 缺少引号 # 错误: {model: sonnet} # 正确: {model: sonnet} # 错误 2: 尾部逗号 # 错误: {model: sonnet,} # 正确: {model: sonnet} # 错误 3: 单引号 # 错误: {model: sonnet} # 正确: {model: sonnet} # 错误 4: 注释 # 错误: {model: sonnet} // 这是注释 # 正确: JSON 不支持注释直接删除 # 步骤 1使用 sed 批量修复 # 修复单引号为双引号 sed -i s//\/g ~/.claude/settings.json # 删除尾部逗号 sed -i s/,\s*}/}/g ~/.claude/settings.json sed -i s/,\s*]/]/g ~/.claude/settings.json # 步骤 2验证 python3 -m json.tool ~/.claude/settings.json方案四停止使用 CC Switch# 步骤 1如果 CC Switch 损坏配置 npm uninstall -g cc-switch # 步骤 2手动管理配置 # 不使用任何配置切换工具 # 直接编辑 ~/.claude/settings.json # 步骤 3API Key 通过环境变量管理 export ANTHROPIC_API_KEYsk-ant-api03-xxx # 不在 settings.json 中存储 Key方案五使用 JSON5 或带注释的配置# 步骤 1如果需要注释 # JSON 不支持注释但可以通过额外字段注释 cat ~/.claude/settings.json EOF { _comment_model: 使用 Sonnet 模型, model: claude-sonnet-4-20250514, _comment_streaming: 启用流式输出, streaming: true } EOF # 步骤 2这些 _comment 字段会被忽略 # 步骤 3验证 python3 -m json.tool ~/.claude/settings.json方案六检查文件编码# 步骤 1检查文件编码 file ~/.claude/settings.json # 应该输出: ASCII text 或 UTF-8 Unicode text # 步骤 2如果不是 UTF-8 iconv -f GBK -t UTF-8 ~/.claude/settings.json ~/.claude/settings.json.utf8 mv ~/.claude/settings.json.utf8 ~/.claude/settings.json # 步骤 3验证 file ~/.claude/settings.json python3 -m json.tool ~/.claude/settings.json4. 各方案对比总结方案适用场景推荐指数难度方案一验证工具排查⭐⭐⭐⭐⭐低方案二重写格式损坏⭐⭐⭐⭐⭐低方案三sed 修复批量修复⭐⭐⭐⭐中方案四停用 CC Switch工具损坏⭐⭐⭐⭐低方案五_comment需要注释⭐⭐⭐低方案六编码修复非 UTF-8⭐⭐⭐低5. 常见问题 FAQ5.1 JSON 格式有哪些常见错误key 必须用双引号key不是key字符串值用双引号value不是value不能有尾部逗号{a:1,}错误不能有注释// comment不允许不能有函数{fn: function(){}}不允许5.2 如何快速验证 JSONpython3 -m json.tool file.json # 或 cat file.json | jq . # 或 node -e JSON.parse(require(fs).readFileSync(file.json,utf8))5.3 CC Switch 为什么损坏配置CC Switch 可能使用非标准的 JSON 写入方式或覆盖了 settings.json 中的其他字段导致格式错误。5.4 JSON 支持注释吗标准 JSON 不支持注释。如果需要注释使用_comment字段代替。5.5 settings.json 的正确格式{ model: claude-sonnet-4-20250514, streaming: true, autoUpdate: true, allowedTools: [Read, Write, Edit], maxConsecutiveToolCalls: 10 }5.6 项目级和用户级 settings.json 都需要正确是的。两个文件都需要符合 JSON 格式。项目级.claude/settings.json和用户级~/.claude/settings.json都会被解析。5.7 如何安全编辑 settings.json使用编辑器的 JSON 语法检查功能如 VS Code或编辑后运行python3 -m json.tool验证。5.8 配置不生效但不报错可能是 JSON 格式正确但配置项名称错误。检查 Claude Code 文档确认正确的配置项名称。5.9 多个配置文件冲突项目级 settings.json 覆盖用户级的相同配置项。如果项目级格式错误会影响整体加载。5.10 排查清单速查表□ 1. python3 -m json.tool 验证 JSON 格式 □ 2. 检查 key 和 value 是否用双引号 □ 3. 删除尾部逗号 □ 4. 将单引号改为双引号 □ 5. 删除 JSON 注释 □ 6. file 命令检查编码是否 UTF-8 □ 7. CC Switch 用户: 停用或手动管理 □ 8. 用 _comment 字段代替注释 □ 9. 验证项目和用户级 settings.json □ 10. 编辑后重新验证6. 总结根本原因配置文件解析错误最常见原因是缺少引号30%、尾部逗号25%和单引号20%最佳实践编辑 settings.json 后始终运行python3 -m json.tool ~/.claude/settings.json验证格式CC Switch 问题CC Switch 可能写入非标准 JSON建议改用环境变量管理 API Key手动编辑 settings.jsonJSON 规范JSON 不支持注释和单引号——用_comment字段代替注释所有 key 和字符串值用双引号最佳实践建议使用 VS Code 等带 JSON 语法检查的编辑器编辑 settings.json编辑器会实时标出格式错误故障排查流程图flowchart TD A[Settings.json 解析错误] -- B[python3 -m json.tool 验证] B -- C{格式正确?} C --|是| D[检查配置项名称] C --|否| E[查看错误位置] E -- F{错误类型?} F --|缺少引号| G[添加双引号] F --|尾部逗号| H[删除逗号] F --|单引号| I[改为双引号] F --|注释| J[删除或改 _comment] F --|编码| K[iconv 转 UTF-8] G -- L[重新验证] H -- L I -- L J -- L K -- L L -- M{验证通过?} M --|是| N[重启 claude] M --|否| O[重写 settings.json] O -- N N -- P{配置生效?} P --|是| Q[✅ 问题解决] P --|否| R[检查 CC Switch] R -- S[停用 CC Switch] S -- T[手动管理配置] T -- Q D -- P