自己做 Windows 下的 Claude 学习手册第一个绕不开的坑就是 Claude Code 的安装。说实话这个工具本身逻辑不复杂——它就是一个跑在终端里的 AI 编程代理你给它一个任务它在项目文件里自己读代码、改代码、跑命令、看报错全程在命令行里跟你对话对应的模型能力也已经到了 Claude 4.5 这一代。但恰恰是“跑在终端里”这几个字让 Windows 用户在安装阶段就劝退了一大半什么“claude 不是内部或外部命令”什么“无法将 claude 项识别为 cmdlet、函数、脚本文件或可运行程序的名称”新手看到这堆报错基本就懵了。这篇是系列第一篇目标只有一个在一台干净的 Windows 电脑上从零把 Claude Code 装好、验证通过、跑起第一段对话。我会把每一步背后的原因也讲清楚而不是只丢命令让你复制粘贴。无论你是没碰过命令行的新手还是从 macOS/Linux 换到 Windows 的老手这套流程都能直接照抄。1. 安装前的环境体检Node.js 与 Git 一个都不能少1.1 Node.jsClaude Code 的运行时引擎先说为什么一定要装 Node.js。Claude Code 是通过 npm 分发的而 npm 是 Node.js 自带的包管理器所以 Node.js 相当于 Claude Code 的运行引擎。没有它后面所有步骤都无从谈起。官方要求 Node.js 18 及以上版本我建议直接装最新的 LTS长期支持版比如目前主流的 20.x 或 22.x没必要刻意装老版本。安装步骤很简单打开 nodejs.org首页就能看到 LTS 版本的下载按钮点进去选 Windows Installer.msi 文件。下载完双击运行一路 Next。有一个步骤叫 “Custom Setup”里面默认勾选了 “Add to PATH”这个必须保持勾选它决定了你后面能不能在任意目录直接敲 node 命令。装完之后必须新开一个终端窗口再验证。这里有个新手最容易踩的坑很多人在安装程序提示“安装成功”后就原地敲命令结果提示找不到 node这是因为 PATH 环境变量的修改不会自动刷新到已经打开的终端窗口里。验证命令node -v npm -v能正常输出版本号就说明 Node.js 环境没问题。顺便说一句如果你电脑上还要跑其他前端项目而且可能会用到多个 Node 版本可以考虑用 nvm-windows 做版本管理但这不是本篇文章的必要条件先跳过也没关系。1.2 Git不一定强制但强烈建议装上Git 装不装其实不影响 Claude Code 的安装本身但会影响你实际用起来的体验。Claude Code 在项目里干活的时候会大量依赖 Git 信息它要看 git diff 来理解你改了什么、看 git status 来判断项目状态、甚至能帮你自动生成 commit。如果你不装 Git这些能力基本就废了而且很多项目级操作会直接报错。安装方式没什么悬念去 git-scm.com 下 Windows 版默认选项一路 Next 就行。Git 安装器在最后会问你要不要调整 PATH 环境变量默认选项是 “Git from the command line and also from 3rd-party software”这个必须保持默认这样 Claude Code 才能在终端里正常找到 git 命令。验证git --version1.3 终端选择Windows Terminal PowerShell 是默认最优解既然要常驻终端用 Claude Code终端的底子得先打好。Claude Code 是一个带颜色、带交互界面的 TUI 工具如果你用 Windows 自带的 CMD 窗口去跑颜色会乱、中文会乱码、界面也不好看体验会大打折扣。我的建议是用 Windows Terminal配合 PowerShell。Windows 11 自带 Windows TerminalWindows 10 可以在 Microsoft Store 里免费安装。装完之后把默认配置文件设为 PowerShell再把字体调成 Cascadia Mono 或者 JetBrains Mono中文显示和符号渲染都会舒服很多。这里还有一个进阶选项WSL。如果你希望获得完全接近 Linux 的体验可以在 WSL2 里装 Ubuntu然后在 Linux 环境里跑 Claude Code这是很多重度开发者的选择。但 WSL 本身又是一套环境配置初学者容易在这里卡住。所以本系列第一篇我们先在原生 Windows 环境把工具跑起来WSL 方案放到后面的文章单独讲。2. 两条安装路线npm 全局安装与原生命令安装2.1 路线一npm 全局安装最通用推荐新手确认 Node.js、Git、终端都就绪后最直接的安装方式就是 npm 全局安装。打开 PowerShell执行一条命令npm install -g anthropic-ai/claude-code这里面的-g表示全局安装意思是把 claude 这个命令装到系统全局路径下你可以在任意目录直接调用它。包名里的anthropic-ai是命名空间说明这是 Anthropic 官方发布的包这一点值得留意——网上有些第三方打包的同名工具认准这个官方作用域就不会装错。安装过程需要从 npm 官方源下载几百个依赖包如果你发现下载速度很慢、甚至卡住不动可以先切换 npm 源再重新安装npm config set registry https://registry.npmmirror.com这个操作只是给 npm 换一个下载速度更快的镜像源属于常规加速手段不影响包的官方性和安全性。装完之后终端最后会显示类似added xxx packages in xx s的信息说明安装成功了。2.2 路线二PowerShell 原生命令安装官方脚本如果你不想走 npmAnthropic 官方也提供了 Windows 原生的安装脚本在 PowerShell 里执行一条命令就行irm https://claude.ai/install.ps1 | iex这条命令拆开来看irm是 Invoke-RestMethod 的简写作用是把 install.ps1 这个脚本从网上下载下来iex是 Invoke-Expression 的简写作用是在当前会话里执行这段脚本。两个命令用管道连起来相当于“下载并运行官方安装脚本”。这个脚本会自动处理下载、解压、配置 PATH 这些步骤对不想接触 npm 细节的人来说更省心。不过有一点要提醒直接从远程管道执行脚本本身是一种信任操作。如果你的安全洁癖比较重可以先用irm把脚本保存到本地检查一遍内容再手动执行这样更稳妥。两条路线选一条就够不建议混用否则可能会同时存在两个安装版本后面排查问题会更绕。2.3 安装后的验证claude --version 与常见失败信号安装完成后的第一件事就是验证命令是否真的可用。打开一个新终端窗口执行claude --version如果能看到一个版本号输出说明安装成功可以跳过第三部分直接看初始化如果提示 “claude 不是内部或外部命令” 或者 “无法将 claude 项识别为 cmdlet”不要慌这是本篇文章要重点解决的问题下面会展开讲。顺便说一句验证的时候建议用 Windows Terminal 而不是 CMD因为 CMD 对 TUI 程序的支持比较差即使装好了在 CMD 里看 Claude Code 的界面也会很别扭。3. 路径与环境变量解决“不是内部或外部命令”的关键3.1 npm 全局安装目录到底在哪“claude 不是内部或外部命令”这个报错90% 的情况是 PATH 环境变量里没有包含 Claude Code 的安装目录。要搞懂这个问题得先知道 npm 把全局包装到了哪里。在终端里执行npm config get prefix正常情况下会输出类似这样的路径C:\Users\你的用户名\AppData\Roaming\npm打开这个目录你会看到 claude、claude.cmd、claude.ps1 这三个文件。它们实际上就是 Claude Code 的启动入口在 CMD 里运行 claude 时系统去找 claude.cmd在 PowerShell 里运行 claude 时系统通过 PATHEXT 找到 claude.cmd 来执行。系统之所以能找到这个目录下的文件就是因为这个目录被加进了 PATH。3.2 PATH 环境变量的正确配置姿势PATH 是什么你可以把它理解成一张“查找清单”。当你在终端里敲一个命令时系统会按顺序扫描 PATH 里的每个目录找到同名文件就执行找不到就报“不是内部或外部命令”。所以只要把 npm 全局目录加进 PATH绝大多数的“找不到命令”问题就解决了。配置入口有两个推荐用图形界面按Win R输入sysdm.cpl回车打开系统属性。点击“高级”选项卡里的“环境变量”。在“用户变量”列表里找到Path选中后点“编辑”。点“新建”把C:\Users\你的用户名\AppData\Roaming\npm添加进去确定保存。必须把所有终端窗口全部关掉重新打开因为已经打开的终端不会自动刷新 PATH。如果你的 npm 全局目录不是默认路径以npm config get prefix的输出为准。另外如果当时安装 Node.js 时取消勾选了 “Add to PATH”还需要把C:\Program Files\nodejs\也加进去不过这种情况比较少见。这里有一个独家提醒网上有些教程让你用setx Path命令修改 PATH但这条命令有 1024 字符的长度限制而且是用整条路径覆盖写回一旦你的 PATH 很长很容易把原有配置截断弄丢。改环境变量这种操作图形界面最安全不建议为了图快用 setx。3.3 PowerShell 执行策略与 cmdlet 识别问题PowerShell 下还有一个独立的问题就是执行策略Execution Policy。如果你遇到的报错不是“找不到命令”而是类似“无法加载文件 ...\claude.ps1因为在此系统上禁止运行脚本”说明 PowerShell 默认禁止运行脚本挡住了 Claude Code 的启动脚本。解决办法是放开当前用户的执行策略Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUserRemoteSigned的意思是本地创建的脚本可以直接运行从网上下载的脚本必须带有数字签名才能运行。npm 生成的 claude.ps1 是在你本地生成的所以这个策略下可以正常跑同时又不会放开对远程脚本的限制。执行时如果弹出确认提示输入 Y 回车即可。改完执行策略同样需要新开终端窗口再试一次。4. 安装完成后的初始化登录、配置与第一个对话4.1 登录认证claude login 与 API Key 两种模式装好之后在终端里直接输入claude回车如果是第一次运行会进入登录引导流程。Claude Code 支持两种认证方式你要根据自己手头有的资源来选第一种订阅账号登录。执行claude login它会打开浏览器引导你完成 Anthropic 账号的 OAuth 授权。登录成功后Claude Code 会检测你账号绑定的订阅套餐按订阅权限来使用模型。第二种API Key 模式。如果你是用 Anthropic API 的开发者可以设置环境变量setx ANTHROPIC_API_KEY 你的API密钥之后新开终端Claude Code 就会自动读取这个 Key按 API 的 token 用量计费。需要注意setx设置的变量只对将来的新终端生效当前窗口里是读不到的。两种方式可以在claude logout之后随时切换。如果你在团队里用的是企业版账号流程会稍有不同登录时跟着引导走就行核心逻辑是一样的。4.2 用 CLAUDE.md 给项目立规矩登录完成后你会进入 Claude Code 的交互式界面看到类似聊天窗口的输入区。这时你可以直接问问题、让它改代码但在开始正经干活之前我强烈建议你先做一件事在项目根目录建一个 CLAUDE.md 文件。这个文件是 Claude Code 的“项目人设说明书”。每次会话启动时它会自动读取这个文件了解你的项目背景、目录结构、构建命令、代码规范、禁止事项。举个例子如果你在 CLAUDE.md 里写上“本项目使用 pnpm 而不是 npm”“测试命令是 pnpm test”“代码风格遵循 Prettier 默认配置”它就会在后续所有操作中遵守这些约定比自己每次手动交代省事得多。你甚至可以偷懒让 Claude Code 帮你生成初始版本在交互界面里输入/init它会扫描当前项目结构生成一份初步的 CLAUDE.md你再按自己的需求增删改。除了项目级的 CLAUDE.md你还可以在用户主目录下的~/.claude/CLAUDE.md里写全局偏好这样所有项目都会遵守。4.3 速度与体验优化终端编码与乱码修复Windows 上的中文化环境有一个老毛病CMD 和部分终端默认使用 GBK代码页 936编码而 Claude Code 输出的是 UTF-8两者不对齐就会出现中文乱码。虽然 Windows Terminal 的默认配置已经比老式 CMD 好很多但如果你在某些环境里仍然看到乱码可以按下面的方案逐级排查。在 CMD 里手动切换到 UTF-8 代码页chcp 65001在 PowerShell 里设置控制台输出编码[Console]::OutputEncoding [System.Text.Encoding]::UTF8还有一种系统级的做法在 Windows 的“区域设置”里勾选“使用 Unicode UTF-8 提供全球语言支持”。这个选项能让整个系统默认走 UTF-8效果最彻底但因为它会影响所有软件的中文显示行为个别老程序可能会因此出现乱码所以建议量力而行能靠终端层面解决就不要动系统设置。5. 高频报错与排查速查表5.1 安装超时、下载慢怎么办npm 全局安装最常遇到的两个问题是“下载慢”和“安装过程中报网络错误”。前面提过先换 npm 镜像源npm config set registry https://registry.npmmirror.com换完源后重新执行安装命令。如果还是卡住可以加日志级别看看到底卡在哪一步npm install -g anthropic-ai/claude-code --loglevel verbose另外如果你的 Node.js 版本低于 18npm 会在安装时报版本不兼容的提示这种情况下先把 Node.js 升级到 LTS 版本再回来重新装。安装过程中如果提示文件占用通常是 VS Code、浏览器这类进程锁住了某些文件把占用程序关掉再试。5.2 版本更新与卸载Claude Code 的迭代速度不算慢隔一段时间就会有新版本官方文档里的功能和模型支持列表也在持续更新。升级命令非常简单npm update -g anthropic-ai/claude-code或者直接强制装最新版npm install -g anthropic-ai/claude-codelatest卸载则是npm uninstall -g anthropic-ai/claude-code这里有一个容易忽略的点卸载工具不会删除你的配置数据。登录状态、主题设置、CLAUDE.md 这些内容默认存放在C:\Users\你的用户名\.claude目录下如果卸载重装想保留配置这个目录不要动如果遇到配置错乱想彻底重置手动删掉这个目录再重新登录即可。5.3 模型识别报错“is not a model this version of claude code recognizes”现在 Claude Code 的版本更新很快模型列表也跟着变最常见的一个坑是你在配置里写了一个当前版本不认识或版本号拼写不对的模型名然后 Claude Code 直接报 “is not a model this version of claude code recognizes”。遇到这个报错排查顺序是这样的第一在交互界面输入/model查看当前版本实际支持的模型列表确认你用的模型 ID 在不在里面。第二如果你项目或全局配置文件里设置了自定义模型名检查环境变量echo $env:ANTHROPIC_MODEL如果这个变量被设成了不存在的模型名用setx ANTHROPIC_MODEL 清空它或者直接改成上面支持列表里正确的模型 ID。第三如果模型确实存在但你本地版本太旧使用npm update -g anthropic-ai/claude-code升级之后再看。5.4 其他常见问题汇总表把我在不同机器上反复踩过的坑整理成一张表方便你直接对照排查。报错或现象可能原因解决办法CMD 提示“claude 不是内部或外部命令”npm 全局目录不在 PATH 中把%APPDATA%\npm加入用户 PATH重开终端PowerShell 提示“无法将 claude 项识别为 cmdlet”PATH 缺失或未刷新同上并确认已完全关闭旧终端PowerShell 提示“禁止运行脚本”执行策略限制Set-ExecutionPolicy RemoteSigned -Scope CurrentUser中文输出乱码终端代码页不是 UTF-8chcp 65001或改用 Windows Terminal安装过程卡住或超时npm 官方源连接慢切换 npm 镜像源后重装运行时报 Node 版本不兼容Node 版本低于 18升级到 Node.js LTS 版本模型名称报错模型 ID 拼写错误或版本过旧/model查看支持列表升级工具检查 ANTHROPIC_MODEL登录后无法使用账号状态或 API Key 无效重新claude login或检查 API Key 配置这套流程我在不止一台 Windows 机器上完整跑过有干净的全新电脑也有装了一堆开发环境的旧机器。实际体验下来绝大多数人的安装失败都不是因为工具本身而是集中在三件事PATH 没刷新生效、PowerShell 执行策略挡脚本、终端编码不对。所以我在正文里反复强调“改完环境变量一定重开终端”这句话它不是走过场而是真正决定成败的一步。最后再分享一个小技巧如果你觉得每次敲claude四个字母太麻烦可以在 PowerShell 的配置文件里加一行别名设置把命令缩短成cc。在 PowerShell 里执行notepad $PROFILE打开配置文件后写入Set-Alias cc claude保存后重开终端输入cc就能直接进入 Claude Code。别小看这种小习惯命令行工具用得顺不顺手往往就是这些细节堆出来的。下一篇我会接着写 Claude Code 的实际使用场景包括代码审查、重构、自动化批量任务这些真正能提效的玩法到时候见。