最近不少读者在看完教程1之后跑来问我几乎同一个问题教程里写了“装 Claude Code 要先装 Node.js”然后呢Node.js 到底是个什么东西官网上一堆红色绿色按钮该点哪个装完怎么知道自己装成功了说实话这个卡点太典型了——你随便打开一篇 Claude Code 安装教程都会看到“请先安装 Node.js”这句话但几乎没有一篇文章愿意把“为什么必须先装、到底怎么装、装错版本怎么办”这件事讲清楚。这篇教程干脆就只解决这一件事把 Node.js 从零装好装到能跑、能验证、能往后走。我会把 Windows、macOS、Ubuntu 三条主流路线都走一遍顺带把所有小白高频遇到的报错和坑都给你列出来。看完这篇你的电脑就是一台“准备好了”的机器可以直接等下一篇装 Claude Code。1. 为什么装 Claude Code 前必须先过 Node.js 这关1.1 Claude Code 本质上是一个 Node.js 命令行程序很多人把 Claude Code 想得很神秘觉得它是不是一个特别重的软件、要装什么大型环境。其实不是。Claude Code 本质上是 Anthropic 提供的一个命令行工具而这个工具是用 JavaScript/TypeScript 写成的跑在 Node.js 运行时上。你可以把 Node.js 理解成一个“翻译官”Claude Code 的代码本身是给计算机执行的高级指令但不是操作系统能直接看懂的原生程序它需要 Node.js 这个运行时环境来解释和执行。这个关系在生活中很好类比。你想玩一个用 Java 写的游戏得先装 Java 运行时你想跑一个 Python 写的脚本得先装 Python 解释器。同理你想在电脑上跑 Claude Code就得先把 Node.js 备好。它不是“装完没有用”的冗余组件而是 Claude Code 的地基。1.2 不装 Node.js 直接装 Claude Code 会怎样我见过很多急性子跳过 Node.js 这一步直接复制安装命令去跑结果在终端里看到一串乱七八糟的报错比如npm: command not found或者node: command not found。这时候人就懵了以为安装包有问题实际上只是缺了前置环境。就算侥幸绕过 npm 安装有些安装脚本内部的检测机制也会直接终止安装提示缺少 Node.js。所以“先装 Node.js”不是流程上的客气话它是硬性的依赖条件。把这一步老老实实走完后面会顺很多。1.3 这一篇要解决什么、不解决什么这篇教程只讲 Node.js 安装范围非常明确检查是否已安装、各平台安装步骤、环境变量配置、版本选择、常见报错排查、安装后的验证方法。至于 Claude Code 本身的安装命令、怎么登录、怎么接第三方模型、怎么在编辑器里配置插件那是系列后面几篇的事这篇不展开。先把地基打牢再往上盖楼这是最稳妥的节奏。2. 动手前先自查你电脑里到底有没有 Node.js2.1 三行命令完成检查很多新手第一步就来问我“要不要先下载什么”其实最该做的是先看看电脑里是不是已经有了。Node.js 这类运行时有个特点装过之后不一定有桌面图标它藏在系统命令行里。检查方法很简单打开你的终端工具——Windows 上打开 PowerShell 或 CMDmacOS 上打开“终端”AppUbuntu 上打开 Terminal然后依次敲三条命令node -v npm -v where node第一条node -v用来查看 Node.js 版本号如果能输出版本号比如v20.19.0说明你电脑里已经有 Node.js 了。第二条npm -v是查看 npm 的版本npm 是 Node.js 自带的包管理器后面装 Claude Code 主要靠它。第三条where nodeWindows 用 wheremacOS/Linux 用which node用来查看 Node.js 被安装到了哪个目录。如果你的输出结果是“command not found”“不是内部或外部命令”之类的话说明这台电脑还没有 Node.js可以直接跳到下面对应你系统的安装章节。2.2 版本号里的玄机LTS 和 Current 的区别如果你检查之后发现自己有 Node.js先别急着高兴还得看版本对不对。Node.js 版本号分成两类LTS 版本和 Current 版本。LTS 是“长期支持版”代表这版本已经足够稳定官方会持续维护好几年适合绝大多数普通用户。Current 是最新功能版迭代快、新特性多但同时稳定性稍弱。判断方法其实很简单版本号是偶数如 v20、v22大概率是 LTS版本号是奇数如 v21、v23就是 Current。对 Claude Code 这种需要稳定运行环境的工具来说安装 LTS 版本始终是最省心的选择。2.3 已有旧版本 Node.js 是否需要卸载如果检查发现你已经有了 Node.js但版本很老比如 v16 甚至更早我的建议是不要急着卸载旧版本。尤其当电脑里还有其他 Node.js 项目在跑时贸然卸载旧版可能会牵连别的项目出问题。稳妥的做法是用版本管理工具后面会专门讲 nvm在系统里同时保留或切换多个版本而不是粗暴地卸载和安装。如果你确定电脑里没有任何旧项目依赖 Node.js那卸载旧版本再装新的也完全可以只是多数情况下没必要走到这一步。3. Windows 安装全流程官网下载、安装向导、环境变量3.1 官网下载前先确认系统位数Windows 用户安装 Node.js 最直接的途径是去官网下载.msi安装包。打开 Node.js 官网后你会看到首页有红色和绿色的两个大按钮。红色按钮对应 Current 版本绿色按钮对应 LTS 版本。作为普通用户请认准绿色按钮。下载之前先确认一下你的 Windows 是 64 位还是 32 位。现在官网默认提供的安装包基本都是 64 位版本如果你电脑是 32 位系统硬装 64 位包会直接弹出兼容性错误比如“由于与当前系统的位数不兼容”之类提示。查看系统位数的方法很简单在 Windows 设置里搜索“系统信息”或者右键“此电脑”选择属性就能看到系统类型备注的是 64 位还是 32 位。3.2 安装向导中那个不能取消的勾选下载好的.msi文件双击运行会弹出安装向导。前几步基本是协议确认和安装路径选择默认路径一般没问题直接下一步即可。真正关键的是中间有一个步骤界面里会有一个列表让你勾选要安装的组件里面有一项叫Add to PATH中文界面里通常显示为“添加到 PATH”。这一项请务必要勾选上。PATH 是 Windows 用来查找可执行程序的环境变量如果没把 Node.js 添加进 PATH后面你在终端里敲node -v就找不到命令虽然软件装了但等于白装。很多网上求助帖里的问题就是这一项没勾上导致的。安装路径尽量不要选带中文的目录也别放在带空格的路径里。虽然大多数情况没问题但对新手来说路径越干净后续排查越省心。3.3 安装完为什么必须重开终端安装完成之后如果你是在安装前就打开了终端窗口那么回到那个旧窗口敲node -v很大概率会提示找不到命令。原因很简单终端窗口启动的时候会读取一次环境变量之后的环境变量变更不会自动刷新到已经打开的窗口里。正确的操作是彻底关掉当前所有终端窗口重新打开一个新的 PowerShell 或 CMD。然后敲node -v你会看到类似v22.13.0的输出这就说明安装成功了。这个“重开终端”的细节能救下不少人的耐心。3.4 PATH 环境变量的手工确认方法如果重开终端之后依然找不到 node那就需要手动检查 PATH 配置了。在 PowerShell 里敲[Environment]::GetEnvironmentVariable(Path, Machine)或者直接按 Win 键搜索“编辑系统环境变量”在“环境变量”弹出框里找到系统变量中的 Path双击查看列表里有没有 Node.js 的安装目录通常是C:\Program Files\nodejs\这样。如果没有手动添加一条也行新建然后填入你的实际安装路径保存之后重新打开终端。这里有一个容易忽略的点Windows 环境变量弹窗里修改完之后所有已打开的终端都要重新打开修改才能生效。4. macOSpkg 安装包和 Homebrew 两条路4.1 pkg 包安装最简单但注意默认路径macOS 用户最省事的方式同样是官网下载安装包。官网首页点击绿色 LTS 按钮得到的.pkg文件双击运行按向导一直继续到底期间可能需要输入你的 Mac 登录密码授权。装完之后Node.js 会被安装到/usr/local/bin/这个目录下同时在/usr/local/下创建lib/node_modules等文件夹。macOS 下验证方式和 Windows 类似打开“终端”App输入node -v和npm -v。如果输出正常版本号就说明装好了。如果提示 command not found多半是目录不在 PATH 里大多数情况下会出现在你用的是旧系统或者手动修改过配置文件。4.2 Homebrew 安装适合需要切换版本的用户如果你日常用 Homebrew 管理软件那用brew install node也能搞定。不过这里我更建议安装 LTS 版本Homebrew 默认安装的 node 常常是最新 Current 版如果你介意稳定性可以用brew install node20这样指定具体大版本。用 Homebrew 安装的好处是后续升级方便一个brew upgrade node就能更新。坏处是 Homebrew 装出来的版本目录和官网 pkg 包不同可能出现在/opt/homebrew/opt/node20/bin这类路径下。这个路径信息在 Homebrew 安装完成后会直接打印在终端里多看两眼别急着关窗口。4.3 Intel 芯片和 Apple Silicon 的路径差异Apple Silicon 芯片用户M1/M2/M3 系列的 Homebrew 安装前缀默认是/opt/homebrew而 Intel 芯片用户是/usr/local。这导致同一条brew install node命令在两台不同芯片的 Mac 上安装位置可能完全不同。如果你之后用 nvm 管理器它会自动处理路径问题但如果你手工改 PATH 或写自动化脚本就一定要先确认你是哪款芯片。查看方法左上角苹果图标 - 关于本机芯片一栏写着“Apple M 系列”还是“Intel”一目了然。5. Ubuntu/Linux别再 apt install nodejs 了5.1 apt 仓库里的版本为什么不够用Linux 用户最常见的安装方式是在终端执行sudo apt install nodejs这确实能装上但我奉劝各位别用这个方式至少别作为首选。Ubuntu 官方软件仓库里的 Node.js 版本往往比最新 LTS 落后很多比如系统发布早的版本仓库里可能还是 v10 或 v12。Claude Code 对 Node.js 有版本要求太老的运行时很容易在安装阶段就报出各种莫名其妙的依赖错误。更重要的是apt 装的 Node.js 自带的 npm 版本可能也和系统版本不匹配。与其装完再折腾升级不如直接从源头上用官方推荐的安装方式。5.2 用 NodeSource 仓库安装指定版本NodeSource 是 Node.js 官方推荐的第三方仓库它能把指定大版本的 Node.js 装进 Ubuntu。在终端执行curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs第一行的setup_20.x表示安装 20.x 系列如果你想要 22.x把网址里的20.x改成22.x即可。这种安装方式的好处是版本可控装完之后的 node 和 npm 版本都比较新也符合 LTS 的标准。执行完上面两条命令之后可以顺手确认一下安装结果node -v和npm -v。如果能看到版本号就说明这一步成功。5.3 nvm 方案多版本管理一步到位如果你不想把 Node.js 绑死在某个特定版本上也不确定以后 Claude Code 可能需要更高版本那 nvm 是更合适的选择。nvm 全称是 Node Version Manager名字已经说明了一切——它专门用来管理电脑上的多个 Node.js 版本想切换随时切换。在 Ubuntu 上安装 nvm终端执行curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash装完之后 nvm 会自动往你的 shell 配置文件里写几行环境变量这时需要重新加载一次配置source ~/.bashrc然后就能用 nvm 安装 LTS 版本了nvm install --lts这条命令会自动装当前最新的 LTS 版本并把默认指向切到它。下次重启终端默认的 node 就是这个版本。5.4 权限问题 EACCES 的快速处理Linux 下装 Node.js 后再装全局 npm 包时偶尔会遇到EACCES: permission denied这类权限报错。这通常是因为 npm 的全局目录没有当前用户的写权限。最简单快捷的解决方案是重新设置 npm 的全局目录到用户目录下而不是用 root 权限强行修改系统目录。mkdir ~/.npm-global npm config set prefix ~/.npm-global然后把这一行写入你的~/.bashrcexport PATH~/.npm-global/bin:$PATH最后执行source ~/.bashrc重新加载配置。之后再用npm install -g安装工具就不会遇到权限问题了。6. 版本选择与常见版本报错24.21.0 为什么装不上6.1 Node.js 版本号规则与 LTS 推荐Node.js 的版本规则是“偶数版本更适合生产环境”。目前在 2025 年前后的主流 LTS 版本是 20.x 和 22.x具体选哪个看你的个人偏好和兼容需求。Claude Code 在安装过程中会检查 Node.js 版本建议选择一个 LTS 大版本确保不要低于官方要求的最低版本。最稳妥的判断方式如果你装的是最新的 LTS 版本且 nvm 或官网能正常显示该版本号那就放心用。6.2 “error installing 24.21.0: is not yet released or is not available”的真相很多人在用 nvm 装 Node.js 时会遇到一个很典型的报错error installing 24.21.0: node.js v24.21.0 is not yet released or is not available这个报错看着很吓人其实原因特别简单你指定安装了一个不存在的版本号。Node.js 的版本发布节奏非常规律不是所有“数字看起来合理”的版本都真实存在。比如 24.21.0 这个具体版本在某个时间点根本还没有被发布出来nvm 去官方源里找不到它就会报这个错。遇到这个报错先停下来检查你输入的版本号是否有误或者查询一下 Node.js 官方发布列表看目标版本是否真的存在。更简单的做法是不要指定那么精确的第三位版本号直接装大版本或者 LTSnvm install 20这样 nvm 会自动选择该系列中最新的可用版本不会因为一个不存在的小版本号而卡住。6.3 用 nvm 管理多个版本的实际体验老手一般都不会只装一个 Node.js 版本。比如你电脑上可能有 v18 的老项目同时还需要 v22 来跑 Claude Code。nvm 可以随时切换默认版本nvm ls nvm use 22 nvm alias default 22nvm ls列出所有已安装版本nvm use 22把当前终端切到 22 版本nvm alias default 22设置默认版本。我个人的习惯是默认版本永远指向 LTS除非某个特定项目需要才临时切换。这里要特别提醒一下nvm 切换版本时全局安装的 CLI 工具比如以后要装的 Claude Code在切换后可能不可用因为它被装在旧版本的全局目录里。遇到这种情况别慌重新执行一次npm install -g就行或者干脆让不同版本都各装一份相应工具。7. 装完后的验证三板斧与新手高频报错7.1 node -v、npm -v、where/which node 三连验证不管你是 Windows、macOS 还是 Ubuntu安装完成后的验证方式都是一致的。打开新的终端窗口输入三条命令逐一确认node -v npm -v where node我的习惯是三条命令全跑一遍而不是只看一个node -v。node -v能看出 Node.js 是否可用npm -v能看出配套包管理器是否正常where nodemacOS/Linux 用which node能看出当前默认的 Node.js 到底在哪个目录。第三点特别重要——如果系统里存在多个 Node.js光看版本号会让人误以为只有一个路径却能直接暴露实际情况。7.2 “node 不是内部或外部命令”的排查顺序这是 Windows 新手最常碰到的报错之一在 PowerShell 或者 CMD 里敲node提示“不是内部或外部命令”在 mac/Linux 上则是“command not found”。遇到这个报错按以下顺序排查检查安装是否完成重新跑一遍安装包确保安装过程没有中途退出。检查安装向导中是否勾选了“Add to PATH”。关掉所有终端窗口重新打开一个新的再试。手动查看系统 Path 环境变量里是否包含 Node.js 目录。如果以上全没问题但依然报错尝试以管理员身份运行终端再试。绝大多数“找不到命令”问题都出在前三条上不需要一开始就去改系统文件。7.3 npm 下载慢的换源操作npm 默认从官方源下载包在国内网络环境下速度偶尔很不理想动不动就卡住。这个问题最实用的解决方案是换用国内镜像源。在终端执行npm config set registry https://registry.npmmirror.com设置之后再执行npm config get registry如果输出的是刚才设置的地址就说明配置成功。换源之后后面安装 Claude Code 等全局工具时的下载速度会有非常明显的提升。这里多说一句换源只影响 npm 下载包的地址不影响任何工具的功能和安全性可以放心操作。如果你对安全特别敏感那些包本身的校验逻辑依然在跑不会被绕过。7.4 其它几个容易踩的坑有一个经常被忽略的问题终端路径。如果你在某个项目目录下打开终端恰好这个目录里存在一个叫node的文件夹某些情况下系统会优先匹配这个文件夹而不是全局的 node 命令。这种情况虽然少见但一旦遇到会让人排查半天。还有一个坑是中文用户名或中文系统名。有些 Windows 用户把系统用户名设成了中文导致 Node.js 安装路径里出现中文字符虽然多数情况下不影响运行但少数全局工具会因此出现奇怪的小毛病。建议遇到诡异问题先检查环境变量里的路径是否存在中文如果有换成纯英文目录最省事。8. Node.js 就绪之后下一步与几条个人建议8.1 安装后的环境状态清单到这里你的电脑应该已经具备以下条件了Node.js 已安装版本是 LTS 系列之一node -v能输出版本号。npm 已可用npm -v能输出版本号。终端能通过where或which找到 node 的安装位置。没有权限报错、版本缺失报错。满足这四条就可以心无旁骛地进入下一步了。8.2 下一篇的安装命令与前置准备下一篇教程会讲 Claude Code 的正式安装流程。在这里先给你打个底到时候会用到 npm 全局安装的方式大概是npm install -g anthropic-ai/claude-code这条路或者用官方提供的安装脚本。到时候会详细说明两种方式各自的适用场景、安装完成后的登录验证步骤以及遇到“组织限制了 Claude 订阅访问”这类账号策略报错怎么处理。现在你唯一需要做的就是确认 Node.js 这条路已经走通。8.3 我踩过几次坑后的几个实在建议最后聊几个我自己的真实体会。第一不要贪新。看到 Current 版本号比 LTS 大就手痒去装 Current真的没必要。Claude Code 需要的是一个稳定的运行环境而不是最新的语法特性。第二不要怕报错。安装 Node.js 时遇到的绝大多数报错都集中在“版本不存在”“环境变量没配好”“权限不够”这三类里照着上面每一步排查基本都能解决。第三如果电脑里已经乱成一团前前后后装过好几个版本的 Node.js最简单的办法是全部卸载干净后用 nvm 重装一遍把混乱状态一次性归零比逐个排查省心得多。等你亲眼看到node -v输出那串版本号这篇的任务就完成了。接下来的事下一篇见。