Claude Code 启动就崩报 Invalid Version 怎么解决？一个 changelog 日期引发的事故
工具起不来是最堵心的一类问题——你连排查的入口都没有，因为所有诊断命令都在工具里面。
Claude Code 有过一次这样的事故，记在 issue #16682（已关闭，80 条评论）里：
Claude Code 2.1.0 crashes on startup - Invalid Version semver parsing error
这篇讲这个具体案例的解法，以及从它身上能提取出来的、对所有启动类崩溃都适用的排查顺序。
一、这次的真因：一个带日期的版本号
semver 是语义化版本号的解析库。它期待看到的是 2.1.0 这种形式，而这次崩溃的原因是——它拿到了一个带日期的字符串。
按 issue #16682 里高赞评论的描述：问题出在 ~/.claude.json 这个文件里的 cachedChangelog 字段。那份缓存的更新日志里有一行是：
## 2.1.0 (2026-01-07)
解析版本号时把日期一起拿去了，semver 解析失败，启动流程就断在那里。
评论给出的改法是把日期删掉，命令是：
sed -i '' 's/## 2.1.0 (2026-01-07)/## 2.1.0/g' ~/.claude.json
说明一下：sed -i '' 这个写法是 macOS 的。Linux 上的 GNU sed 是 sed -i 后面不跟空串。所以照抄前先确认自己的系统——或者干脆用编辑器打开 ~/.claude.json，找到那一行手动删掉日期，更稳妥。
这是社区在 issue #16682 里给出的绕过办法，不是官方文档收录的做法。 但同一个帖子里，官方的 Collaborator 回复了一句：正在推一个补丁版本修复这个问题。
所以这条的完整图景是：社区先找到了手改的办法，官方随后发版修掉了。
二、这个案例真正的价值：优先升级
对今天的你来说，2.1.0 这个具体版本已经是过去式了。这条 issue 值钱的地方在于它示范了启动类崩溃的一个通用规律：
启动崩溃很多时候是「工具读了一个自己写的坏文件」，而不是你的配置有问题。
这次是缓存的 changelog。类似的还可能是缓存文件、状态文件、日志索引——都是工具自己维护、你从来没碰过的东西。
所以撞上启动崩溃，第一反应不该是「我改了什么」，而应该是：
- 先升级。 如果这是个已知问题，官方多半已经修了。启动不了的话，用你原来的安装方式重装或更新。
- 再考虑清缓存。 手动删掉那个出问题的缓存字段/文件。
- 最后才怀疑自己的配置。
顺序反过来的话，你会花很长时间检查自己的 settings.json，而问题根本不在那。
三、启动类崩溃的通用排查顺序
Claude Code 官方对启动不了的情况有几个明确的入口，按这个顺序走：
第一步：claude doctor（在 shell 里跑，不是在会话里）
官方明确写了：如果 claude 根本起不来，就在 shell 里跑 claude doctor，而不是在会话内跑 /doctor。这是启动崩溃场景下唯一还能用的诊断命令。
第二步：claude --safe-mode
官方在排查性能问题时给的这条，对启动问题同样有用——它禁用所有自定义（插件、MCP 服务、hook）。
如果 safe mode 能起来、正常模式起不来，那问题就锁定在你的自定义配置里了，接下来只要一个个排除。这一步能把搜索范围砍掉一大半。
第三步：看具体报错文本，对官方错误参考
官方错误参考里有几条是启动/安装相关的：
| 报错 | 官方处理 |
|---|---|
Could not locate the Claude CLI on PATH | 装 CLI；确保目录在 PATH；用 which claude（Windows where claude）验证 |
Installation was killed before it could finish (exit code 137) | 重新运行安装 |
The connection dropped while downloading the update / Download timed out | 提高网络稳定性；重试 claude update |
Claude Code process exited with code N | 查进程日志了解退出原因；重启；持续失败就升级或重装 |
Error: Settings file exceeds the 2MiB limit | 设置文件超了 2MiB，减小它 |
最后那条值得留意——设置文件有 2MiB 的大小上限。正常人写不到这么大，但如果有脚本往里面追加内容（比如自动记录什么东西），就有可能撞上。
四、command not found: claude 是另一回事
要区分两种「起不来」：
- 崩溃：命令找到了，跑起来了，然后挂了 → 本文前面讲的那些
command not found：命令根本没找到 → PATH 问题，跟崩溃无关
第二种的处理是官方 Could not locate the Claude CLI on PATH 那条：
which claude
Windows：
where claude
没输出就是不在 PATH 里。这种情况下再怎么删缓存、改配置都没意义，因为压根没跑起来。
五、动手改 ~/.claude.json 之前
本文引用的那条社区办法要改 ~/.claude.json，动手前有两句话：
先备份。
cp ~/.claude.json ~/.claude.json.bak
这个文件里有不少东西，改坏了会引出新问题。备份一份的成本是零。
改完确认 JSON 还是合法的。 手动编辑最常见的事故是漏了个逗号或引号。如果你的系统上有 python，可以这样验：
python -m json.tool ~/.claude.json > /dev/null && echo OK
输出 OK 就是合法的。不合法的话，你会从一个崩溃换到另一个崩溃。
六、另一类「起来了但用不了」：信任与插件
除了崩溃和找不到命令，还有第三类启动期问题——它起来了，但一堆东西不生效。这类通常跟工作区信任和插件有关，官方错误参考里有好几条：
Ignoring N permissions.allow entries from ... this workspace has not been trusted
成因是工作区没有被信任，于是你配的权限允许项被忽略了。处理是信任这个工作区（在 VS Code 里操作，或者用 claude --trust-workspace），并复查权限设置。
这条的表现很迷惑：它不崩溃、不报错阻断，只是你配的规则悄悄失效了。如果你发现「明明加了允许项还是每次都问我」，先看是不是这个。
Error: Workspace not trusted
启动远程控制时撞上的，处理是在 VS Code 里信任工作区。
插件相关的三条：
| 报错 | 官方处理 |
|---|---|
Marketplace "<name>" is registered from an untrusted source | 确认插件来源的合法性；从可信来源重新添加 |
Plugin archive integrity check failed | 插件存档损坏或被篡改；重新下载、从官方来源安装 |
references ${user_config.*} in a shell-form command | 插件命令里在 shell 形式的命令中引用了 ${user_config.*}；改用 JSON 数组形式的命令 |
前两条属于安全类拦截，不是故障。尤其第二条——完整性校验失败意味着那个文件跟预期不符，不要想办法绕过它，去官方来源重新装。
后台会话相关的两条：EUNKNOWN: unknown error, uv_spawn（官方处理：升级到最新版、检查系统资源是否充足、看详细日志）和 CLAUDE_CODE_PROCESS_WRAPPER: launcher ...（检查启动器进程是否在运行、看完整错误消息）。这两条都指向进程启动层面，跟本文开头那个 semver 崩溃是同一大类——都不是你的配置写错了。
七、总结
- issue #16682 那次的真因是
~/.claude.json里cachedChangelog中带日期的版本号导致 semver 解析失败，社区办法是删掉日期，官方随后发了补丁版本修复。 - 对今天的你，这个案例的价值是那条规律：启动崩溃常常是工具读了自己写的坏文件，不是你的配置有问题。
- 排查顺序：先升级 → 再清缓存 → 最后才怀疑自己的配置。
- 启动不了时，
claude doctor要在 shell 里跑，--safe-mode能一步把范围砍到「是不是自定义配置的锅」。 command not found是 PATH 问题，跟崩溃不是一类，先用which claude分清。- 手改
~/.claude.json先备份，改完验 JSON 合法性。
本文的社区办法与官方回复来自 anthropics/claude-code 仓库 issue #16682（已关闭），其余官方内容来自 Claude Code 官方错误参考与排查文档，核对日 2026-08-08。文中版本号为该 issue 记录的历史情况，当前版本请以官方为准。