最近折腾了一件事：老项目必须使用 Node.js 14.17.1，而 Claude CLI 又需要较高版本的 Node.js 才能运行。

一开始看起来，这似乎是一个典型的 Node.js 版本

一、为什么项目必须使用 Node.js 14.17.1？

这个项目是一个比较老的 Vue Web 项目，依赖版本已经锁定。

由于项目本身比较稳定，并没有升级 Node.js 和相关依赖的计划，所以开发环境需要保持：

Node.js 14.17.1

而新版 Claude Code 对 Node.js 版本有要求，使用 npm 安装的版本需要较新的 Node.js 才能正常运行。

于是最开始很容易得出一个结论：

要么升级项目 Node.js，要么为了 Claude 把 Node.js 切换到高版本。

但实际上，这两个方案都不是最理想的。

二、最开始的想法：使用 nvm 来回切换 Node.js

我的电脑本身使用的是 nvm-windows（nvm4w） 管理 Node.js。

目前安装了多个版本：

• Node.js 14.17.1

• Node.js 20.19.6

• Node.js 22.20.0

所以最开始的思路非常直接：

项目开发时：

nvm use 14.17.1

需要使用 Claude 时：

nvm use 22.20.0

看起来没什么问题。

但实际使用下来体验并不好。

首先，npm 全局包是跟随不同 Node.js 环境隔离的。

切换 Node.js 版本之后，可能出现：

• 全局 npm 包不一致

• CLI 命令找不到

• PATH 解析发生变化

• 不知道当前到底使用的是哪套 Node.js 环境

更重要的是：

项目开发过程中，我并不希望为了使用 Claude 而频繁切换 Node.js。

所以我开始重新思考这个问题。

三、关键发现：官方 claude.exe 自带运行时

后来发现了一个非常关键的事情。

Windows 下的 Claude Code 官方原生版本实际上是一个：

claude.exe

这个官方二进制版本自带自己的 Node.js 运行时。

这意味着：

如果 claude 命令最终执行的是 C:\claude\claude.exe，那么系统当前的 Node.js 是 14.17.1、20.19.6 还是 22.20.0，都不会影响 Claude 自己的运行。

而 npm 安装的：

@anthropic-ai/claude-code

则属于另一种情况。

它本质上是一个 Node.js 程序，需要由系统中的 Node.js 来启动。

于是问题的思路发生了变化。

原本想解决的是：

如何让 Claude 适应 Node.js 14？

后来变成了：

如何让 claude 命令永远解析到自带运行时的 claude.exe？

这个方向一下就清晰了。

四、现场勘察：机器上其实已经有解决问题的东西

于是开始对当前环境进行排查。

结果发现，电脑上的环境其实已经具备了大部分条件。

1. nvm-windows 已经安装多个 Node.js 版本

目前有：

14.17.1
20.19.6
22.20.0

其中项目需要：

14.17.1

2. 官方 claude.exe 已经存在

在开始配置之前，先确认本机是否已经有 Claude Code 的 Windows 原生版本。

我这台电脑之前已经手动下载过 Claude Code 的 Windows 原生二进制文件，因此本地已经存在：

C:\claude\claude.exe

这个文件是 Windows 下的原生 claude.exe，不依赖当前通过 nvm 激活的 Node.js 版本。

可以直接执行：

Get-Item C:\claude\claude.exe

或者：

C:\claude\claude.exe --version

确认文件可以正常运行。

如果本机还没有这个文件，可以通过 Claude Code 官方渠道获取 Windows 原生版本。

目前 Claude Code 官方仓库已经将 npm 安装方式标记为 deprecated，并推荐 Windows 用户使用原生安装方式。

也可以关注官方 GitHub 仓库：

Claude Code 官方 GitHub 仓库

如果你手动下载的是某个版本对应的 Windows claude.exe，可以将它放到一个固定目录，例如：

C:\claude\claude.exe

这里之所以选择单独的：

C:\claude

而不是放到 nvm 的 Node.js 目录中，是为了让 Claude CLI 和项目 Node.js 环境彻底解耦。

最终结构就是：

C:\claude
└── claude.exe

C:\nvm4w
└── nodejs
    └── 当前激活的 Node.js

这样无论执行：

nvm use 14.17.1

还是：

nvm use 22.20.0

C:\claude\claude.exe 都不会跟着 nvm 改变。

注意： 不要把 claude.exe 放进 C:\nvm4w\nodejs 这样的 nvm 当前版本目录中。因为这个目录会随着 nvm use 切换，容易再次产生命令解析和版本隔离问题。

我这次的做法就是把官方原生版本固定放在：

C:\claude\claude.exe

然后通过 PATH 和命令解析，让 claude 始终优先使用这个文件。

3. 先确认 claude.exe 本身可以独立运行

不要急着修改 PATH。

先直接使用完整路径运行：

C:\claude\claude.exe --version

如果能够正常输出类似：

2.1.252 (Claude Code)

说明这个原生版本本身没有问题。

然后再执行：

Get-Item C:\claude\claude.exe

确认文件确实存在。

这一步非常重要，因为后面我们排查的是：

claude
    ↓
PATH
    ↓
到底解析到了哪个文件

而不是排查：

claude.exe 本身能不能运行

先把这两个问题拆开，后面的排查会简单很多。

4. npm 全局安装的 Claude 也存在

电脑上还存在 npm 全局安装的 Claude Code。

而且由于使用了 nvm，实际上存在多套 npm 全局环境。

例如：

C:\nvm4w\nodejs\

以及：

%APPDATA%\npm\

这些位置都可能存在：

claude
claude.cmd
claude.ps1

5. C:\nvm4w\nodejs 实际上是一个符号链接

nvm-windows 的一个重要特点是：

C:\nvm4w\nodejs

并不是固定的 Node.js 安装目录。

它实际上会指向当前激活的 Node.js 版本。

例如：

C:\nvm4w\nodejs
        ↓
C:\nvm4w\nodejs\v14.17.1

或者：

C:\nvm4w\nodejs
        ↓
C:\nvm4w\nodejs\v22.20.0

所以，当执行：

nvm use 22.20.0

和：

nvm use 14.17.1

之后，C:\nvm4w\nodejs 所代表的内容实际上发生了变化。

这也成为后面问题的关键。

五、真正的问题：一个被自更新废掉的 npm shim

接下来开始模拟不同 Node.js 环境下的 claude 命令解析。

这时候真正的问题终于暴露出来了。

当 Node.js 22.20.0 激活时：

nvm use 22.20.0

执行：

claude

命令首先命中了：

C:\nvm4w\nodejs\claude.cmd

这套 npm shim 是正常的。

但是切换到：

nvm use 14.17.1

之后，情况发生变化。

因为 Node.js 14.17.1 对应的目录里并不存在这个 claude.cmd。

于是 Windows 会继续按照 PATH 顺序向后查找。

最终命中了：

C:\Users\Administrator\AppData\Roaming\npm\claude.cmd

问题就在这里。

这个 claude.cmd 本身并没有真正包含 Claude，它只是一个 npm shim。

打开之后，可以看到它最终指向类似：

C:\Users\Administrator\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe

但执行时却报错：

'"C:\Users\Administrator\AppData\Roaming\npm\node_modules\@anthropic-ai\claude-code\bin\claude.exe"'
不是内部或外部命令，也不是可运行的程序或批处理文件。

乍一看，非常像 Node.js 14 版本太低。

但实际上并不是。

六、继续往下查：claude.exe 到底去哪了？

既然 shim 指向的：

bin\claude.exe

不存在，那就直接进入目录查看。

结果发现：

bin\claude.exe

已经变成了类似：

bin\claude.exe.old.1781764501843

也就是说：

Claude Code 自更新过程中，把原来的 claude.exe 改名成了 .old.* 文件。

但是之前生成的 npm shim 并没有同步更新。

于是最终形成了这样的状态：

claude.cmd
    ↓
@anthropic-ai/claude-code
    ↓
bin\claude.exe
    ↓
不存在

而真正存在的是：

bin\claude.exe.old.1781764501843

所以这个 shim 当然无法启动。

七、为什么这个问题看起来特别像 Node.js 版本问题？

实际上是两个问题刚好叠加到了一起。

第一个问题：nvm 导致命令路径发生变化

Node.js 22 激活时：

C:\nvm4w\nodejs\claude.cmd

存在。

所以：

claude

可以正常运行。

切换到 Node.js 14 后：

C:\nvm4w\nodejs\claude.cmd

不存在。

Windows 就继续向 PATH 后面查找。

第二个问题：PATH 后面的 npm shim 又刚好坏了

最终找到：

%APPDATA%\npm\claude.cmd

但这个 shim 指向的：

bin\claude.exe

已经被自更新改名。

于是最终报错。

所以整个过程看起来就像：

Node 14
   ↓
claude
   ↓
报错

很容易得出：

Claude 不支持 Node 14。

但真正的链路实际上是：

Node 14
   ↓
nvm 当前环境
   ↓
C:\nvm4w\nodejs\claude.cmd 不存在
   ↓
继续查找 PATH
   ↓
%APPDATA%\npm\claude.cmd
   ↓
shim 指向失效的 bin\claude.exe
   ↓
启动失败

所以这类问题排查的时候，不要只盯着报错文本。

先看看：

Get-Command claude

以及：

where.exe claude

到底找到了谁。

八、最终方案：让 Claude 和项目 Node.js 彻底分离

最终我采用的是一个比较简单的方案：

让项目继续使用 Node.js 14.17.1，而 Claude 永远使用官方自带运行时的 claude.exe。

整个方案分成三层。

第一层：用户 PATH 前置 C:\claude

将：

C:\claude

放到用户 PATH 的前面。

这样新打开的终端中：

claude

优先解析到：

C:\claude\claude.exe

而不是 npm shim。

第二层：处理 %APPDATA%\npm 中的坏 shim

为了兼容一些已经打开的终端，以及避免 PATH 中仍然存在旧 shim 带来问题，对：

%APPDATA%\npm

下的：

claude
claude.cmd
claude.ps1

进行了重定向。

它们最终都指向：

C:\claude\claude.exe

当然，原文件全部提前备份。

所以这不是简单删除，而是：

原文件
   ↓
备份
   ↓
新的重定向
   ↓
C:\claude\claude.exe

这样即使某个旧终端最终命中了 %APPDATA%\npm\claude.cmd，启动的依然是官方的：

C:\claude\claude.exe

第三层：nvm 固定项目使用 Node.js 14.17.1

项目开发环境继续保持：

nvm use 14.17.1

于是最终形成：

Windows
│
├─ Node.js
│   └─ 14.17.1
│
├─ Claude
│   └─ C:\claude\claude.exe
│       └─ 自带 Node.js 运行时
│
└─ 项目
    └─ node / npm / npm run xxx
        └─ Node.js 14.17.1

两边完全独立。

九、最终使用效果

现在日常开发的时候，只需要：

nvm use 14.17.1

然后：

claude

即可。

Claude 正常启动。

而项目内部执行：

node -v

仍然是：

v14.17.1

例如 Claude 在项目目录中执行：

cmd /c "node -v & npm -v"

得到的依然是项目自己的 Node.js 环境。

【实践截图：cmd /c "node -v & npm -v" → v14.17.1】

这时候实际上存在两个完全不同的运行时：

Claude
    ↓
C:\claude\claude.exe
    ↓
Claude 自带运行时


项目
    ↓
node / npm
    ↓
nvm
    ↓
Node.js 14.17.1

它们并不冲突。

十、目前我的最终方案

现在这台 Windows 机器上的环境基本就是这样。

1. nvm 固定项目使用 14.17.1

项目开发保持：

Node.js 14.17.1

不需要为了 Claude 修改项目环境。

2. Claude 直接使用官方 claude.exe

命令最终解析到：

C:\claude\claude.exe

不需要为了 Claude 切换到 Node.js 22。

3. 原有 npm 全局包继续保留

没有直接卸载原来的 npm 全局 Claude。

对于有问题的 shim，只进行了重定向。

原始文件全部进行了备份。

4. 所有修改都可以回退

这次没有采用：

卸载 → 重装 → 重新配置

而是尽量采用：

备份
+
PATH 调整
+
文件重定向

因此出现问题时，可以直接恢复备份。

如果需要切回 Node.js 22，也依然可以：

nvm use 22.20.0

整个 Node.js 环境并没有被破坏。

十一、这次实践中几个比较重要的结论

1. 工具运行时和项目运行时是两回事

这是我认为这次最重要的一个结论。

不要简单地认为：

Claude 使用 Node.js，所以 Claude 必须和项目使用同一个 Node.js。

实际上：

Claude 运行时
≠
项目运行时

Claude 官方 claude.exe 自带自己的运行时。

而项目：

node
npm
npm run

依然可以继续使用 nvm 管理的：

Node.js 14.17.1

两者可以完全独立。

2. 真正需要关注的是 claude 命令最终解析到了谁

Windows 下执行：

Get-Command claude

或者：

where.exe claude

非常重要。

尤其是电脑上同时存在：

• npm 全局安装

• nvm

• 官方 exe

• cmd shim

• PowerShell shim

这些东西的时候。

你看到的：

claude

并不一定就是你以为的那个 Claude。

3. npm 全局安装并不意味着所有东西都只有一个目录

npm 全局包虽然有自己的目录，但应用程序运行文件、自更新文件、shim 等可能分散在不同位置。

这次遇到的情况就是：

claude.cmd

还存在。

但是它指向的：

bin\claude.exe

已经被自更新改成：

claude.exe.old.*

最终造成 shim 失效。

4. 报错信息不一定就是根因

看到：

Node.js 版本太低

或者：

Claude 无法启动

不要马上开始升级 Node。

先检查：

Get-Command claude

以及：

where.exe claude

看看命令解析链。

很多环境问题，真正的根因其实是：

PATH
shim
符号链接
版本目录
残留文件

而不是软件本身。

5. 环境问题尽量采用“配置 + 新增 + 备份”

这次没有选择卸载重装，而是尽可能采用：

先备份
↓
修改配置
↓
增加重定向
↓
验证
↓
需要时恢复

这种方式对于开发环境尤其重要。

因为环境一旦被彻底重装，很容易出现：

一个问题没解决，又引入了三个新问题。

十二、后续还可以继续折腾什么？

现在：

Claude + Node.js 14.17.1

已经基本跑通。

但如果继续优化，其实还有不少可以研究的方向。

例如：

1. 让项目自动使用指定 Node.js

现在还需要：

nvm use 14.17.1

能不能做到：

进入项目目录
↓
自动切换 Node.js 14.17.1

这样就不用每次手动执行。

2. 不同项目自动匹配不同 Node.js

例如：

项目 A
→ Node.js 14.17.1

项目 B
→ Node.js 20.19.6

项目 C
→ Node.js 22.20.0

进入目录自动识别项目配置并切换 Node.js。

对于同时维护多个老项目和新项目的人来说，这会方便很多。

3. 给特定 CLI 单独指定 Node.js

以后可能还会遇到类似：

项目 Node.js 14
Claude 自带运行时
某个 CLI 必须 Node.js 22
另一个 CLI 必须 Node.js 20

这时候就可以进一步研究：

如何让不同 CLI 使用不同的 Node.js，而不影响当前项目。

4. 防止 Claude 自更新再次破坏 npm shim

这次的问题本质上和自更新后的文件变化有关。

后续也可以进一步研究：

如何让 Claude 自更新和 npm shim 之间彻底解耦。

5. 把整个环境配置做成脚本

最终甚至可以做到：

安装 Node.js
↓
安装 nvm
↓
配置项目 Node.js
↓
配置 Claude
↓
修复 PATH
↓
生成 shim
↓
完成环境检查

全部自动化。

这样以后换电脑，也不用重新手动排查一次。

十三、实践截图

下面预留一些截图位置，方便后续补充实际部署过程。

① 报错现场

【实践截图：claude 报错：不是内部或外部命令】

本地图片：

② nvm 切换到 14.17.1

【实践截图：nvm use 14.17.1 + node -v】

本地图片：

③ claude 命令解析结果

【实践截图：Get-Command claude 第一个命中 C:\claude\claude.exe】

本地图片：

④ 验证 Claude 内执行项目命令

【实践截图：cmd /c "node -v & npm -v" → v14.17.1】

本地图片：

⑤ 坏 shim 修复后验证

【实践截图：claude --version 输出 2.1.252 (Claude Code)】

本地图片：

⑥ 备用：病根——被自更新改名的 exe

【实践截图：bin\claude.exe 已变为 claude.exe.old.*】

本地图片：

⑦ 备用：PATH 解析全景

【实践截图：Machine/User PATH 优先级】

本地图片：

总结

这次排查经历了一个比较典型的思维转变。

最开始以为：

项目 Node.js 14
+
Claude 需要高版本 Node.js
=
Node.js 版本冲突

于是第一反应是：

nvm use 14
↓
开发项目

nvm use 22
↓
使用 Claude

但实际排查之后发现，真正的问题并不是 Node.js 版本冲突。

关键在于：

claude
↓
到底解析到了哪个文件？

最终解决方案反而非常简单：

Windows
│
├─ nvm-windows
│   └─ Node.js 14.17.1
│
├─ Claude
│   └─ C:\claude\claude.exe
│       └─ 自带运行时
│
└─ 项目
    └─ node / npm
        └─ Node.js 14.17.1

Claude 有自己的运行时，项目也有自己的运行时。

只要让：

claude

正确解析到：

C:\claude\claude.exe

就没有必要为了 Claude 修改老项目的 Node.js 环境。

所以以后如果在 Windows 上遇到类似：

Claude 报错，而且看起来像 Node.js 版本不兼容。

可以先别急着升级 Node。

先执行：

Get-Command claude

以及：

where.exe claude

先看看 claude 到底是谁。

对于我来说，这次实践真正解决问题的关键，就是把：

“Claude 必须匹配项目 Node.js”

转变成了：

“Claude 和项目可以使用完全独立的运行时。”

现在项目继续稳定运行在：

Node.js 14.17.1

同时 Claude Code 也可以正常工作。

后面如果继续把自动切换 Node.js、多项目版本映射、CLI 独立运行时以及开机自启这些方案完善起来，再继续记录。