命令版本管理

昨天还能通过的检查，今天在安装步骤之后报了个陌生错误。代码没动，配置没动，唯一的变量是工具自己升级了。

这种故障的根源通常不在工具本身，而在于「用它的人没有决定用哪个版本」。把版本当成依赖来管理，问题就从玄学变成流程。

还要知道一个默认行为：原生安装默认会在后台自动更新。你的开发机可能在你不知情时就换了版本，这既解释了「昨天还好好的」，也说明生产环境必须自己掌握升级时机。

先确认自己到底在跑什么

最直接的一条：

claude --version

它只给版本号。要排查环境问题，换成诊断命令：

claude doctor

诊断报告会额外告诉你安装方式、可执行文件路径、平台、自动更新状态，以及设置文件有没有校验错误。装了两份、PATH 指错、自动更新通道设错，这几类问题都能从这里看出线索。字段名和展示形式以当前版本为准。

版本号怎么读，风险就怎么估

多数 CLI 工具沿用「主版本.次版本.补丁」的三段式。Claude Code 迭代快，但这套读法仍然能帮你估风险：

变化位置	含义	建议动作
补丁位	修缺陷、小改进	一般可以直接升
次版本位	新增功能，尽量向后兼容	升完跑一遍关键脚本
主版本位	可能改动默认行为	先读发布说明，再分批升

版本节奏和具体规则以官方发布说明为准，不要把这张表当成承诺。它只是让你在看到一个数字时，知道该花多少注意力。

升级与回退

升级优先用内置入口，它知道你是怎么安装的：

claude update

也可以走原来的安装渠道，例如用 npm 全局安装的就用 npm 重装，用 Homebrew 的就用 brew 升级。包名与命令以官方安装页当前给出的为准，不同平台不一样。

回退要指定确切版本：

claude install <版本>                          # 原生安装的直接指定版本
npm view @anthropic-ai/claude-code versions   # 用 npm 的，先看有哪些版本
npm install -g @anthropic-ai/claude-code@<版本>

两条路选一条即可：原生安装用 claude install 最省事，npm 安装则用 npm 自己的版本语法。Homebrew 对旧版本支持有限，必要时用 npm 临时装一个指定版本覆盖。回退后跑一次 claude doctor，确认实际在跑的就是你指定的那个版本。

升级前先留退路

主版本升级前，花十分钟做三件事，出问题时能立刻退回：

cp -r ~/.claude ~/.claude.bak              # 备份配置与会话
tar -czf claude-scripts.tar.gz ./scripts   # 归档用到 CLI 的脚本
claude --version > versions-before.txt

Windows 上用资源管理器把 %USERPROFILE%\.claude 复制到别处同样可以，不必记命令。备份之后，另找一个干净环境装上新版本——容器、另一台机器，或用版本管理器切一个 Node 环境——拿两三条最关键的命令各跑一遍，把输出和旧版并排比对。比对重点不是格式，而是结论和退出码：同样的输入，新版给出的判断变了没有，失败时返回的码还是不是脚本预期的那个。

确认无碍再升正式环境，并把新版本号写进项目记录。回滚顺序也提前想好：先退回旧版本，再查发布说明，最后才改脚本。顺序反了，容易在故障里改出第二个故障。

在流水线里钉死版本

生产环境最忌讳 @latest。把版本写死，升级就变成一次有意识的提交：

- name: Install Claude Code
  run: npm install -g @anthropic-ai/claude-code@<版本>

Docker 镜像同理，把版本写进构建步骤，并给镜像打上同样的标签。如果项目用 npx 调用，可以把确切版本放进 devDependencies，再用 npm script 执行，团队成员安装后拿到的是同一份。

钉版本不等于永远不升。正确的姿势是定期、主动地升级一次，跑完回归再改版本号；而不是每天被动接受最新版。

几个项目各用各的版本

三种做法，按隔离程度从高到低：

1. 用 Node 版本管理器隔离。 全局 npm 包挂在对应 Node 版本下，给不同项目配 .nvmrc，切目录就切环境。
2. 用 npx 临时调用。 版本号写在命令或 package.json 里，不污染全局；代价是首次要下载。
3. 给二进制改名。 把不同版本存成 claude-<版本>，调用时写全名，简单直接，CI 里也好用。

如果团队只有一两个项目，第三种最省心；项目多、环境复杂时，第一种更稳。

卸载与重装：哪些该留，哪些该清

重装前先分清 ~/.claude 下哪些是「你的东西」。配置文件、个人偏好、自定义命令、会话记录都在这里；只想修安装问题，重装程序即可，这个目录不用动。想彻底从零开始，才需要把它整体移走或删除。

一个稳妥做法是先改名而不是直接删：

mv ~/.claude ~/.claude.old

重装后如果一切正常，再决定什么时候清理旧目录；万一新环境有问题，把名字改回来就恢复了。直接 rm -rf 没有后悔药。

升级或重装失败，多数不是程序本身的问题，按现象排查更快：

现象	常见原因	处理
claude update 报权限错误	全局安装目录属于系统账户	不要直接加 sudo 硬装；改用版本管理器，或把 npm 全局前缀指到用户目录
装完仍是旧版本	PATH 里有另一份可执行文件在前	用 claude doctor 看实际路径，删掉或调整顺序
启动报配置字段弃用	新版本改了设置项名称	按警告提示改名，不要忽略
命令能跑但结果和之前不同	升级引入了行为变化	查发布说明，按旧版本对比输出，必要时回退

最后一条最值得记住：能跑不等于没变。版本管理的目标不是用上最新的，而是让每次行为变化都由你决定。想把这类「默认值变化」的风险放进更大的工程视角，可以对照幂等性来看：同样的输入重复执行，结果应当可预期。

发布说明要读哪几行

升级前扫一遍发布页，重点不是新功能，而是会改变既有行为的条目。常见关键词可以当成信号灯：

关键词	含义	风险
Breaking change	破坏性改动	高，可能直接报错
Behavior changed	行为变了但参数没变	最高，静默出错
Deprecated	标记弃用，未来删除	中，留出迁移时间
Removed	已经删除	高，旧写法失效
Renamed	改名，旧名可能仍可用	低到中

最需要警惕的是「行为变了但参数没变」。它不会让脚本失败，只会让输出悄悄不同，等你发现时可能已经跑了很多次。遇到这类说明，先在隔离环境用旧脚本跑一遍，对比结果再决定。

开发机可以追新，生产环境要可预期；把版本当作依赖来管，故障就从「莫名其妙」变成「可以回滚」。想复习版本差异会怎样影响执行过程，可以回看命令执行流程。下一节开始进入具体命令，先看最基础的启动方式——启动交互式 REPL。