先说个判断Claude Code 这类终端型 AI 编程工具和 Windows 天然有些“不亲”。不是它本身难装而是 Windows 的控制台环境、Node.js 的全局包路径、环境变量生效机制和 macOS/Linux 差了很大一截。这个教程的任务很明确让一台普通的 Windows 10/11 机器装上 Claude Code并完成 API Key 配置最后能在项目目录里直接叫它干活。适合第一次接触命令行 AI 编程助手的人也适合之前装过但启动就报错的人。我尽量按真实操作顺序写包括哪个窗口输什么命令、配置完为什么打不开、API Key 到底该放哪。1. 项目拆解这个教程到底在装什么1.1 需要解决的三类问题把“Windows 安装 Claude Code 详细教程含 API Key 配置”拆开看核心不是“下载一个安装包”而是三个环环相扣的问题安装环境、工具本体、身份认证。先说安装环境。Claude Code 不是绿色的 exe它本质上是一个 Node.js 命令行工具通过 npm 分发。也就是说Windows 上必须先有 Node.js而且要有能正常工作的 npm。很多人在这一步就埋下了雷装了 Node 但是没加 PATH或者装的是太老的版本后面全崩。再说工具本体。Claude Code 的安装动作很简单一条 npm 全局安装命令就能完成。但 Windows 上“安装成功”和“能启动”是两回事。npm 全局包会放进某个目录这个目录如果不在 PATH 里你敲claude系统就完全不认识。最后是 API Key。Claude Code 需要身份认证典型方式就是配置一个 API Key。这一步看起来是复制粘贴实际上因为 Windows 环境变量的生效机制很反直觉很多人配置完以后当前窗口读不到于是反复重装越弄越乱。理解了这三层接下来的操作就顺理成章了。1.2 为什么 Windows 的坑都集中在环境配置Windows 和 macOS、Linux 最大的区别在于环境变量的生效方式。在类 Unix 系统里export一次当前 shell 立刻生效在 Windows 里设置用户环境变量用的是setx或图形界面但已经打开的终端窗口不会自动刷新必须新开一个窗口。PATH 的情况也类似。很多人装完 Node.js 以后发现node -v能用就以为万事大吉。可是node能跑不代表claude能跑因为claude是安装在 npm 全局目录里的这个目录不一定在 PATH 里。如果不在Windows 根本不会去那里找命令。另外还有一个隐藏问题权限。如果你是用管理员账号装的 Node.js但日常终端是普通权限或者反过来npm 全局目录的写入权限可能不一致安装时会不断报EPERM这类权限错误。这些问题都不是 Claude Code 本身造成的但实际卡人卡得最多。1.3 适用场景与不适合的场景适合这条安装路线的人很明确你用的是 Windows想在本地终端里用 Claude Code 干活而且希望用 API Key 而不是网页登录方式来做认证。安装完成后它和 IDE 没有强绑定不管你用 VS Code、VS Code 的衍生版还是 JetBrains 系列只要有一个能打开终端的项目目录就行。不太适合的情况也有。如果你连 API Key 都还没申请、也没有任何模型调用额度装完也只能看到命令行闪一下什么都做不了。所以先确认自己手里有可用的 API Key再往下折腾。如果你平时完全不碰终端只会在网页上和 AI 对话那 Claude Code 的体验大概率不符合你的习惯因为它要管理的是整个目录、文件和命令行环境。2. 安装前的环境准备先把 Node.js 和终端弄干净2.1 安装 Node.js LTS并确保 PATH 里有 nodeWindows 上装 Node.js最省事的办法就是去官网下载 LTS 版本的安装包。建议选 20 以上的版本不要选太老的 16 或 14Claude Code 对运行时版本有要求太老的 Node 会带来一堆兼容问题。安装的时候有一步特别重要安装向导里的 “Add to PATH” 选项一定要勾上。这一步如果漏了后面不管装多少次 Claude Code都会被“找不到命令”卡住。正常安装完成后关掉旧终端重新打开 PowerShell 或者终端先跑两条命令node --version npm --version两条命令都能输出版本号说明 Node 和 npm 已经进入 PATH。如果node --version有输出但npm --version报错通常是因为 Node 安装目录不完整或者 PATH 里有重复路径建议直接卸载重装 Node.js。不要手动去挪node.exe的位置。有人为了路径好看把 Node 安装目录搬到了别处结果 PATH 里还写着原来的路径启动时永远找不到命令。这种事我见过不止一次最靠谱的方式就是让安装包管理路径。2.2 确认 npm 全局路径可写Node 装好以后Claude Code 会以“全局包”的形式安装到 npm 的 global 目录。所以在正式安装之前最好先看一眼这个目录在哪里以及它是否可写。在 PowerShell 里执行npm config get prefix常见的输出是C:\Users\你的用户名\AppData\Roaming\npm这个路径就是 npm 全局命令的所在位置。如果你想确认它当前有没有问题可以执行一个无害的全局命令npm root -g能正常输出路径就行。如果输出路径是在C:\Program Files\之下那么全局安装大概率需要管理员权限。这种情况下有两种选择一是用管理员身份打开 PowerShell 安装二是修改 npm 的全局目录到用户目录下但普通使用者没必要折腾直接用管理员窗口跑安装命令就够。2.3 重开终端的意义把 Node 装好之后我强烈建议你立刻关掉当前终端再重开一个新的。这不是仪式感而是 Windows 环境变量的生效机制决定的PATH 的改变只会在新终端里生效。有时候你安装完 Node 后当前窗口里node已经能用了因为安装器会尝试更新当前进程的环境变量。但更多时候旧窗口里跑claude依然找不到命令因为 PATH 里还没有 npm 全局目录。所以把“安装后重开终端”养成习惯能省掉很多毫无必要的排查时间。3. 安装 Claude Code从 npm 全局安装到首次启动3.1 执行全局安装命令打开一个新的 PowerShell 窗口直接执行全局安装npm install -g anthropic-ai/claude-code注意这里是-g表示全局安装。如果你漏掉-g包只会装进当前目录claude命令不会进入系统依然没法全局使用。安装过程会比较安静正常情况下没有任何交互等它跑完会显示类似added X packages的提示。这一刻“装成功”只完成了一半另一半是让命令能被 Windows 找到。如果你之前已经装过旧版本可以用同样的命令重新执行或者先看一下当前版本npm list -g anthropic-ai/claude-code然后执行升级npm update -g anthropic-ai/claude-code升级前最好先确认当前版本不是最新版避免重复下载。3.2 验证命令是否被识别安装完成后在同一个窗口里直接验证claude --version如果终端输出了一个版本号说明全局命令已经被 PATH 找到了安装环节基本完成。如果提示claude 不是内部或外部命令或者无法识别 claude说明 npm 全局目录还没有进入 PATH。这个时候不要急着重装先排查路径。还有一种验证方式是使用npx临时运行npx anthropic-ai/claude-code --version这条命令只是“临时调用”它能运行不代表全局命令已经可用因为npx会自动去找模块。真正判断安装是否成功的依据还是claude --version。3.3 处理 command not foundclaude命令找不到九成问题是 PATH 缺少 npm 全局目录。先执行npm config get prefix拿到路径比如C:\Users\你的用户名\AppData\Roaming\npm。然后按Win R输入sysdm.cpl打开“环境变量”在“用户变量”里找到Path把上面的 npm 目录加进去再点确定重开终端。如果你嫌图形界面麻烦也可以用命令把当前用户的 PATH 追加进去但命令行改 PATH 容易改错新手我更推荐 GUI 方式至少每次改动都是可见的。还有一种很少见但真实存在的情况PowerShell 的执行策略限制了.ps1脚本导致 npm 生成的脚本无法运行。这时候终端会提示类似“无法加载文件因为在此系统上禁止运行脚本”的错误。解决办法是在 PowerShell 里执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser然后再重开终端。这个操作只影响当前用户不会动系统级策略比较安全。4. API Key 获取与配置这是最容易翻车的半程4.1 API Key 从哪里来Claude Code 需要 Key 来调用模型接口。和网页版登录不同API Key 通常是在模型服务商的开发者后台里创建的一串字符串类似sk-开头复制出来以后要自己保管好。我没有办法在教程里替你去某处注册账号因为这涉及个人支付方式和账号权限。你只需要知道API Key 和你的账号余额、模型权限是绑定的创建之后要确认账号有可用的额度否则即使配置得再完美调用时依然会提示鉴权失败。好的习惯是创建 Key 时给它一个可识别的名字比如“Windows-ClaudeCode”方便以后在后台查看。如果 Key 泄露了立刻回后台吊销并重新生成不要抱侥幸心理。4.2 临时配置和永久配置拿到 API Key 后配置方式有两种临时配置和永久配置。临时配置适合只想马上试一次的人。在 PowerShell 里执行$env:ANTHROPIC_API_KEY sk-你的key这条命令只对当前终端窗口生效关掉窗口就没了。好处是不用污染系统环境变量坏处是每次打开新窗口都要重新设置比较麻烦。永久配置推荐用setxsetx ANTHROPIC_API_KEY sk-你的key注意setx写入的是用户环境变量最关键的一点是它不会改变当前已经打开的终端窗口里的环境变量。所以执行完setx后不要在当前窗口里马上测试先去开一个新的 PowerShell 窗口再验证。如果你想用图形界面配置也可以走“系统属性 - 环境变量 - 用户变量 - 新建”这条路径变量名填ANTHROPIC_API_KEY变量值填 Key。效果和setx一样。4.3 验证 Key 是否真正生效配置完以后新开一个 PowerShell 窗口先看环境变量是否真的进来了echo $env:ANTHROPIC_API_KEY如果输出你设置的 Key说明环境变量生效。如果什么都没输出说明窗口不是新的或者setx设置的对象不对。大部分情况是当前窗口没重开直接重开就行。然后启动一次会话来验证claude正常情况下不会再提示缺少 API Key而是直接进入交互界面。你也可以用非交互模式快速验证claude -p 你好请用一句话回复-p模式适合脚本调用会直接输出模型回复然后退出。第一次验证时建议用这句话如果能看到回复说明 Key 有效、模型权限正常、网络连接也没问题。5. 第一次上手在 Windows 终端里跑起来5.1 在项目目录启动Claude Code 的核心价值是“在项目里干活”所以启动方式不是随手打开终端就敲claude而是先进入一个项目目录。比如你有一个项目放在D:\code\demo-project先切过去cd D:\code\demo-project然后再启动claude这个时候它会读取当前目录的上下文包括项目的文件结构、Git 状态等。第一次启动时可能会有一小段欢迎或权限说明按提示确认就行。如果你在一个空目录里启动它也能用但很多能力体现不出来因为缺少上下文。我的建议是第一次体验时选一个你不怕被改坏的示例项目先感受一下它能做什么再慢慢把真实工作交给它。5.2 常见交互方式进入交互界面后你就直接像聊天一样发指令就行。比如这个项目用了什么技术栈它会根据目录文件来回答。也可以让它做具体修改帮我看看 README.md 里有哪些过时的内容并给出修改建议。如果只想快速查看帮助输入/help想要退出会话输入/exit或者按Ctrl C中断当前操作。Windows 终端里偶尔会出现输入法快捷键和命令快捷键冲突的情况比如Ctrl C被输入法占用这时候直接在终端里切到英文输入法再试问题基本能解决。5.3 离开会话与清理用完以后建议不要直接把终端窗口留在项目目录里挂着。如果是临时测试直接/exit退出如果之后还要继续保持目录干净即可。API Key 已经写进环境变量不担心会话退出后丢失。还有个容易被忽略的点claude每次交互都会消耗模型 token不是本地免费功能。所以不要有事没事就开着好几个会话挂着按需开启用完就退。6. Windows 安装和配置的常见问题排查6.1 排查一条线如果安装后出问题不要东查西查按一条线走下来最快先确认 Node.js 和 npm 能运行再确认 npm 全局路径存在再确认claude --version能输出版本再确认 API Key 环境变量存在最后确认账号有余额。绝大多数问题都出在这五步的某一环。你可以开一个 PowerShell 窗口依次执行node --version npm --version npm config get prefix claude --version echo $env:ANTHROPIC_API_KEY哪个环节空着或者报错就去修哪个环节不要一上来就重装 Claude Code。6.2 高频问题速查表现象常见原因解决办法node或npm无法识别未安装 Node.js或 PATH 缺少 Node 目录安装 Node.js LTS确认安装时勾选 Add to PATH重开终端claude无法识别npm 全局目录不在 PATH用npm config get prefix找到路径手动加入用户 PATH重开终端安装时报EPERM权限错误npm 全局目录没有写入权限用管理员身份打开 PowerShell 重新执行安装命令启动后提示缺少 API Key环境变量未配置或未生效执行setx后重开终端或用临时配置$env:ANTHROPIC_API_KEY调用时报认证失败API Key 错误、已吊销或账号无额度回控制台重新生成 Key检查账号余额和模型权限长时间无响应或连接失败本机无法正常访问公网检查网络连通性和系统防火墙确认能访问外部服务后重试终端输出中文乱码控制台代码页问题执行chcp 65001切换到 UTF-8或修改 Windows Terminal 默认编码PowerShell 提示禁止运行脚本执行策略限制执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser后重开窗口6.3 几个我实测后觉得值得注意的操作习惯我先说一个容易踩的不要抱着“一次性永久解决”的心态去折腾环境变量然后频繁改系统 PATH。Windows 的用户 PATH 里堆太多东西以后命令查找会变慢而且容易互相干扰。正确做法是只添加真正需要的 npm 全局路径不要把所有工具的安装目录都塞进去。第二个建议是 API Key 不要随便复制到聊天框、截图或公共文档里。哪怕是打码截图也有被打码还原的风险。真要用就只往环境变量或密钥管理工具里填。不要把 Key 写进项目的.env文件然后随手提交到版本仓库这种泄漏事件在开发者社区里屡见不鲜。第三点是关于setx的坑。setx的变量值长度有限如果你把一大串异常格式的 Key 塞进去可能被截断。设置完毕后务必执行echo $env:ANTHROPIC_API_KEY确认完整。如果发现值不对用 GUI 环境变量窗口重新编辑最可靠。还有个容易被忽略的小习惯在 Windows 上安装完工具以后第一件事是重开一个干净的终端窗口而不是在旧窗口里反复怀疑命令没装好。我在实际使用中大多数“命令不存在”的报错最后都是因为没开新窗口。记住这一点整个安装体验会顺畅非常多。
