Claude Code 保姆级安装教程：从零配置 Node.js、Git 与 VS Code 环境

说实话我一开始是有点抗拒写 Claude Code 安装教程的——这玩意儿明明一条命令就能装完为什么网上还能搜出一堆“踩坑实录”后来帮几个完全不懂编程的朋友远程捣鼓了一遍我才发现真正卡人的根本不是npm install而是前置环境里的各种小坑Git 装到一半 PATH 选错、Node.js 在 LTS 和 Current 之间纠结半天、PowerShell 直接拦截脚本不让运行。每一个都是小事串起来就是一下午。这篇就是给从零开始的读者准备的保姆级流程。目标很直接让完全没配过开发环境的人跟着步骤把 Claude Code 装好、认证好并在 VS Code 里跑通第一轮对话。不需要任何编程基础只要会复制粘贴命令、能读懂报错信息照着走半小时内大概率能搞定。1. 装之前先弄明白三件事它是什么、靠什么运行、为什么总有人装不上1.1 Claude Code 不是一个可以“双击安装”的软件很多人对“安装软件”的认知还停留在“下载一个 exe、双击安装、桌面上出现图标”的模式。Claude Code 完全不属于这个模式它是 Anthropic 发布的一款命令行编程助手一个跑在终端里的 AI 工具。你可以直接在终端里告诉它“帮我写一个批量改名脚本”或者“这个项目为什么一直报错”它会在当前目录下读代码、改代码、执行命令。它没有图形界面没有桌面图标启动方式就是在终端里输入claude。正因为它是一个命令行工具所以安装方式跟普通软件不一样需要通过 npmNode.js 自带的包管理器来分发安装。整个安装过程本质上就是“把官方发布的包从 npm 仓库拉到你电脑的全局环境里”。你可以把终端理解成一个没有按钮的聊天框你输入命令电脑给你回结果。Claude Code 就是住在终端里的一位编程助手而 npm 是它进入你电脑的“输送管道”。管道没接好后面自然就卡住了。1.2 依赖链Node.js 提供运行环境Git 负责项目协作安装 Claude Code 之前电脑上至少要准备好两样东西Node.jsClaude Code 本身是 Node.js 程序运行它必须有 Node.js 运行时。Node.js 安装时会自带 npm 包管理器后续安装 Claude Code 本体就靠它。Git这不是运行 Claude Code 的必要条件但强烈建议装。Claude Code 在真实项目开发里会大量涉及 Git 操作比如自动帮你创建提交、查看 diff、处理分支。如果电脑上连 Git 都没有后续使用会非常别扭。而且很多项目的初始化流程也会自动调用 Git 命令。我见过有人在没有 Git 的环境里硬装 Claude Code装是装上了但真到项目里用的时候寸步难行最后还是回来补装。既然这篇是保姆级教程那就一次性全配齐。顺序上先把 Git 和 Node.js 准备好再装 Claude Code是最省事的路径。1.3 为什么总有人在安装上卡一下午这里我把见过的几类失败原因提前列出来你等会儿遇到报错可以对号入座版本选错Node.js 装了 Current 尝鲜版跟 npm 包的兼容性容易出问题。环境变量PATH没配对Git 装完了在命令行里输入git却提示“不是内部或外部命令”。PowerShell 执行策略限制安装完成后运行claude提示“禁止运行脚本”。网络下载超时npm 官方仓库在某些网络环境下访问特别慢安装到一半就失败。目录权限问题npm 全局安装目录没有写入权限报EACCES或EPERM。这些坑我在后面的章节里都会逐一给出处理方式。你先有个印象到对应步骤再回来看。再补充一个重要的心理预期你装到什么程度算成功标准就两条第一claude --version能正常输出一个版本号第二输入claude能进入一个交互式对话界面。整篇教程都是朝着这两个标准去的。2. 第一关装好 Git并把 PATH 一次配对2.1 下载 Git 时怎么选版本Git 官网是 git-scm.com进去之后页面会自动识别你的操作系统。Windows 用户会看到大大的 “Download for Windows” 按钮点击后会跳到下载页。在下载页里找 “64-bit Git for Windows Setup” 这个链接现在绝大多数电脑都是 64 位系统选这个就不会错。下载完成后是一个 .exe 安装包双击开始装。安装向导的语言默认是英文不需要改一路 Next 基本不会点错。但有几个关键选项会影响后面的使用我单独拎出来讲。2.2 安装向导里那三个最容易选错的选项虽然大部分步骤可以直接 Next但有几个选项真的不能乱选Select Components选择组件这一页保持默认即可。如果你用的是 Windows 11 且系统里装了 Windows Terminal我建议把 “Add a Git Bash Profile to Windows Terminal” 也勾上之后在终端里切换 Git Bash 会更方便。Adjusting your PATH environment调整 PATH 环境变量这一页必须选中间那个 “Git from the command line and also from 3rd-party software”。这是默认选项正常情况下不用改。如果你不小心选成了第一个 “Use Git from Git Bash only”那在 PowerShell 或 CMD 里输入git就会提示找不到命令。后面验证的时候如果出问题十有八九就是这一项选错了。Line Ending Conversions换行符转换保持默认的 “Checkout Windows-style, commit Unix-style line endings” 就好。这个选项处理的是 Windows 和 Linux/macOS 之间换行符的差异涉及多人协作项目时比较重要默认值是最稳妥的。安装向导里还有一个 “Default branch name” 的设置新版 Git 默认推荐main保持默认即可不影响 Claude Code 使用。2.3 验证并配置 Git 用户信息装完之后按 Win 键输入 PowerShell打开 Windows PowerShell。在命令行里输入git --version如果输出类似git version 2.4x.x.windows.1的信息说明 Git 已经装好且 PATH 也生效了。然后顺手配置一下全局用户名和邮箱。这一步是给 Git 提交代码时用的Claude Code 在帮你生成提交记录时也会读取这两个信息git config --global user.name 你的名字 git config --global user.email 你的邮箱邮箱不要求是真实常用的但格式要合法。如果你不填之后某些 Git 操作会报 “Please tell me who you are” 的提示到时候再回来补也行。这里有个小经验环境变量PATH修改之后必须关掉当前终端窗口再重新打开一个配置才会生效。很多新手在验证时发现命令还是找不到其实不是没配上而是没有重开终端。3. 第二关Node.js 版本别乱选装完还得验证 npm3.1 LTS 还是 Current答案只有一个打开 Node.js 官网 nodejs.org首页会直接给两个下载按钮。左边写着LTSLong Term Support长期支持版右边写着Current当前最新版。很多新手会在这一步纠结其实答案只有一个装左边的 LTS别碰 Current。Current 版本虽然新但社区生态里的各种包有时候还没完全跟上兼容性风险更高。像 Claude Code 这类工具对 Node.js 的版本要求通常是“某个 LTS 版本以上”所以直接装最新的 LTS比如目前主力的 20.x LTS是最稳的。下载.msi安装包双击安装。3.2 安装选项与 npm 全局目录安装 Node.js 时路径建议保持默认Windows 下通常是C:\Program Files\nodejs\。不要改到带中文或空格的路径虽然不一定出问题但没必要给自己挖坑。安装向导里有一页会问你要不要安装 “Tools for Native Modules”这个默认不勾就好。它的作用是帮你安装编译 native 模块所需的一堆工具比如 Python、Visual Studio Build Tools而 Claude Code 是纯 JavaScript/TypeScript 项目用不到这些。勾了反而会多下载几个 GB 的东西白白浪费时间。这里还要注意安装向导里有一个Add to PATH的复选框默认是勾选状态。保持勾选这决定了后续node和npm命令能不能在命令行里直接识别。装完同样在 PowerShell 里验证node --version npm --version两条命令都有版本号输出说明 Node.js 和 npm 都正常了。多说一句 npm 的全局安装目录。Windows 下 npm 把全局包安装在%APPDATA%\npm这个目录通常是C:\Users\你的用户名\AppData\Roaming\npm。正常情况下安装 Node.js 时这个目录会被加进系统 PATH所以后续装完 Claude Code命令行能直接识别claude命令。如果之后你遇到 “claude 不是内部或外部命令” 的问题第一反应就是检查这个目录在不在 PATH 里后面我会专门讲。3.3 网络下载太慢时切换镜像源npm 默认从官方源registry.npmjs.org拉取包有些网络环境下官方源访问很慢安装到一半就卡住或者反复超时。如果你遇到这种情况可以切换到一个通用的公共镜像源来加速npm config set registry https://registry.npmmirror.com设置完之后再执行 npm install速度会有明显提升。想确认当前源的话运行npm config get registry输出你设置的那个地址就说明已经生效。注意镜像源只是把 npm 包仓库做了一份同步副本包的内容完全一致不影响安装结果。如果之后想换回官方源把地址改回https://registry.npmjs.org/就行。4. 第三关装 Claude Code 本体看懂那一行命令的每一段4.1 全局安装命令前面两关都过了之后真正安装 Claude Code 就剩一条命令。在 PowerShell 里执行npm install -g anthropic-ai/claude-code这句话要拆开看不然你出了问题都不知道错在哪npm install调用 npm 包管理器执行安装。-gglobal的缩写表示全局安装。加了这个参数后装出来的claude命令在系统任何目录下都能直接调用不加的话只能在你当前项目里用后面会很麻烦。anthropic-ai/claude-code这是 Claude Code 在 npm 仓库里的完整包名。anthropic-ai是组织名scopeclaude-code是包名本身。执行之后终端里会开始滚动下载信息最后出现类似added 2xx packages in 12s或者显示up to date、changed X packages之类的文字都代表安装过程正常结束。如果网络状况不好过程中可能会报ETIMEDOUT、ECONNRESET、ENOTFOUND这一类错本质都是网络请求失败解决方式就是换前面提到的镜像源或者换个网络环境重试。4.2 养成立刻验证的习惯安装结束不代表万事大吉要验证装完没有。接着输入claude --version如果出现一个版本号比如1.x.x说明claude命令已经能被系统识别。这一步就顺手做了不要跳过。如果在这里遇到 “claude 不是内部或外部命令” 或claude: command not found先别慌这多半是全局目录没有加入 PATH 导致的。Windows 上的处理步骤运行npm config get prefix记下输出的全局目录。按 Win 键搜索“编辑系统环境变量”打开“环境变量”设置。在“用户变量”里找到Path这一项点编辑新增一行写入 npm 输出的那个全局目录Windows 下默认是C:\Users\你的用户名\AppData\Roaming\npm。确定保存重开一个 PowerShell 窗口再试claude --version。macOS / Linux 上如果遇到command not found通常是因为 npm 的全局 bin 目录不在 PATH 里。运行npm prefix -g查看路径然后在~/.zshrc或~/.bashrc里加一行export PATH$(npm prefix -g)/bin:$PATH再source一下配置文件。4.3 登录认证三步走验证命令可用之后在终端里直接输入claude程序会进入交互式界面首次使用会要求登录认证。流程大致三步终端里会出现一个链接或者提示你按回车在浏览器中打开让你完成账号登录。用你的 Claude 账号登录然后授权 Claude Code 访问该账号。授权完成后浏览器显示成功回到终端提示已经认证成功接着进入可以输入问题的对话界面。这里说明一下账号适用性如果你订阅了 Claude 的某个付费方案比如 Pro 或 Max直接用订阅账号登录即可。如果你走的是 API 按量付费路线也可以设置一个环境变量ANTHROPIC_API_KEY指向你的 API Key跳过浏览器登录那一步。登录成功后你会看到终端里出现一个输入框。等它出现提示符就说明全部搞定了。可以试着问一句“你好能正常收到消息吗”看它能不能回复。5. 第四关在 VS Code 里跑通第一轮对话5.1 为什么推荐搭配 VS Code 使用单独在 PowerShell 里用 Claude Code 当然没问题但日常写代码的时候我更推荐在 VS Code 的集成终端里启动它。原因很简单Claude Code 在修改代码时如果能直接操作 VS Code 当前打开的项目目录你就不用来回切换窗口。它能读上下文、改文件、执行命令你在旁边看着变化体验会好很多。VS Code 没有的话去 code.visualstudio.com 下载安装即可安装过程全默认下一步没什么需要特别配置的。装好后打开任意一个项目文件夹按快捷键Ctrl 键盘上数字1左边那个键可以直接打开集成终端。5.2 把默认终端切到 Git BashWindows 上VS Code 集成终端默认是 PowerShell。正常来说 PowerShell 也能跑claude命令但如果你在之后的开发里发现某些命令在 PowerShell 中行为不太一样可以把默认终端切换成 Git Bash——就是你在第二章装 Git 时一起装好的那个环境。切换方法在 VS Code 终端面板右侧点下拉箭头选择 “Select Default Profile”然后在列表里选 Git Bash。之后每次新建终端默认就会打开 Git Bash。Git Bash 对命令行工具的语法处理更接近 Linux 环境各种开源项目的安装脚本在里面跑也更顺。切好之后在终端里把环境整体验证一遍git --version node --version npm --version claude --version四条命令都有输出说明环境完全就绪。这一步花不了十秒钟但是能帮你把所有潜在问题一次性揪出来避免后面排查起来到处都是坑。5.3 第一次真正跑起来在 VS Code 集成终端里输入claude进入交互界面等提示符出现后给它一个具体的任务。注意不要一上来就让它“帮我写个网站”这种大而空的需求最好是一个具体、可以在当前目录立刻验证的小任务。比如新建一个空文件夹然后对它说“在当前目录创建一个 index.html实现一个带有完整 CSS 样式的个人主页首页包含标题、介绍文字和一个按钮。”你会发现它会先确认一下任务内容然后创建文件、写入代码一步到位。这样一个完整闭环下来你对它到底怎么工作就有体感了。这一步也建议你顺便感受下它的交互方式按CtrlC或输入/exit退出用/help查看内置命令熟悉之后再慢慢上手复杂项目。6. 装完必看我踩过的四个坑和对应解法6.1 PowerShell 拦截脚本这个问题出现概率最高这是我在帮朋友远程装的时候遇到概率最高的报错。装完 Claude Code输入claude结果 PowerShell 直接甩出一段红色报错无法加载文件 C:\Users\xxx\AppData\Roaming\npm\claude.ps1因为在此系统上禁止运行脚本。这段报错的本质是 Windows 默认的 PowerShell 执行策略Execution Policy不信任.ps1脚本而 npm 生成的启动脚本恰好是.ps1格式所以被拦住了。解决方案是在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令的含义是允许运行本地脚本远程下载的脚本需要有可信签名。它只对当前用户生效不会影响整个系统的安全策略。执行时如果弹出确认提示输入Y回车即可。之后再运行claude就正常了。如果你实在不想动执行策略也可以改用 CMD 或 Git Bash 来启动claude绕开 PowerShell 的检查。但既然终端以后要天天用建议还是把执行策略调过来这是一劳永逸的做法。6.2 “claude 不是内部或外部命令”的完整排查链路这个问题分两种情况。一种是安装过程中网络中断包没下载全虽然 npm 显示完成了但实际目录里文件不完整另一种就是 PATH 问题。我建议的排查顺序是先运行npm list -g --depth0看看anthropic-ai/claude-code是否在全局包列表里。如果在说明安装是成功的问题就出在 PATH。运行npm config get prefix拿到全局目录。Windows 下把%APPDATA%\npm加到用户 PATHmacOS / Linux 下把 bin 目录加进 shell 配置。如果npm list里根本没有这个包重新执行一次npm install -g anthropic-ai/claude-code这次建议先切换镜像源或换个网络环境。下面是几种常见问题的速查表建议截图保存报错信息或现象根本原因处理办法输入git提示“不是内部或外部命令”Git 安装时 PATH 选项选错重装 Git在 Adjusting your PATH environment 保持中间选项node -v有输出但npm -v没输出npm 所在目录未加入 PATH检查安装目录把 nodejs 目录加入用户 PATH运行claude提示“禁止运行脚本”PowerShell 执行策略限制 .ps1 脚本Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserclaude --version提示 command not found全局目录不在 PATH或安装未成功用npm list -g --depth0确认安装再检查/新增全局 npm 目录到 PATH安装过程报 ETIMEDOUT / ECONNRESET网络请求 npm 官方源失败切换公共镜像源后重试安装时提示 EACCES / EPERM全局目录没有写入权限Windows 检查%APPDATA%\npm权限Mac / Linux 使用 sudo 或修正 npm prefix 目录权限6.3 版本升级与卸载命令Claude Code 更新频率不低官方经常加新功能。升级命令npm update -g anthropic-ai/claude-code或者想强制装到最新版npm install -g anthropic-ai/claude-codelatest卸载的话npm uninstall -g anthropic-ai/claude-code卸载后claude命令就没了但 Git、Node.js、VS Code 这些环境本身不受影响。我个人的习惯是每次看到 Claude Code 发新版本公告就跑一遍 update避免因为版本过老导致某些新指令不兼容。6.4 建议用 nvm 管理 Node 版本但别在第一步就折腾如果你以后还要折腾其他 Node.js 项目不同项目可能要求不同的 Node 版本到那时候全局只装一个 Node.js 就不太灵活了。这时候可以考虑装 nvm-windowsWindows或 nvmmacOS / Linux来管理 Node 版本。nvm 的好处是可以在不同 Node 版本之间一键切换nvm install 20 nvm use 20用 nvm 管理环境之后npm 全局包的安装路径会跟着当前 Node 版本走Claude Code 需要重新装一遍。所以如果你现在已经装完 Claude Code暂时不想折腾的话就不急着上 nvm等以后真有需要再做迁移。新手阶段先把版本固定的环境用熟比一步到位更重要。如果你每一步都照着做大概率在第四个步骤就已经能看到claude的版本号了。我最后再分享一个小习惯装好之后先别急着跑大型项目拿一个小文件夹或者玩具代码练练手感受一下它的回复节奏和交互方式。我见过太多人一上来就丢一个大型代码库进去结果上下文太长、任务太模糊体验反而很差。从小的、明确的任务开始你会更快摸清楚该怎么跟它配合。