1. 安装之前先把环境盘点清楚最近总有人问我Claude Code 在 Windows 上到底能不能用是不是只支持 Mac 和 Linux我一开始也以为要装 Linux 子系统或者搞个虚拟机才能跑。但实际试下来Claude Code 官方对 Windows 的 支持要比想象中成熟很多尤其 2024 年末到 2025 年初这波更新之后Windows 原生终端里直接跑已经是常规操作。这个安装教程的核心就是两件事把环境准备好把坑绕开。先说结论在 Windows 上装 Claude Code 需要满足四个前置条件Node.js 18 及以上版本建议直接上 LTS长期支持版我用的 Node 20 和 22 都跑得很稳。一个能用的终端Windows Terminal 是首选PowerShell 5.1 也能跑但体验差一截。已经注册好的 Claude 账号用于安装完成后的登录授权。Git可选但推荐因为 Claude Code 大量操作围绕 Git 仓库展开diff 检查、提交记录分析全靠它。很多人一上来就执行安装命令结果报 EPERM、EACCES、ENOENT 之类看不懂的错其实八成是 Node.js 没装好或者 npm 全局目录权限不对。所以我建议先把这套底子打牢后面安装就是一条命令的事。1.1 检查 Node.js 是否已经就位打开 PowerShell直接输入node -v npm -v如果能看到类似v20.x.x和10.x.x的输出说明 Node 环境已经准备好了。如果提示node不是内部或外部命令说明 Node.js 还没装或者没加入 PATH。安装 Node.js 有个细节容易被忽略安装器会让你选择是否自动安装必要的原生工具那个选项建议勾上。它本质上是帮你把 Python、Visual Studio Build Tools 这些编译链一起装好虽然 Claude Code 本身是纯 JS 命令行工具不需要本地编译但以后你装其他 npm 包时可能会碰到需要 node-gyp 的情况一次到位能省掉很多折腾。1.2 Windows Terminal 和 PowerShell 策略检查Windows 自带的 PowerShell 默认对脚本执行卡得很严有时候安全策略会直接拦截 npm 包里的脚本。可以在安装前先看一眼当前策略Get-ExecutionPolicy -List大多数个人电脑上本地用户策略是Restricted但你在普通 PowerShell 窗口里跑 npm 命令一般不受影响真正会触发拦截的是后面我们用npx或者定义命令别名的时候。如果你遇到了“此系统上禁止运行脚本”的报错那个时刻再改不迟不需要提前动全局策略。我的建议是能不动系统安全设置就不动。Claude Code 的官方安装方式走的是全局 npm 包这条路你只要保证 Node.js 装好、npm 源可用接下来基本不会碰到执行策略的坎。1.3 为什么推荐 Windows Terminal有人习惯用系统自带的多功能终端或者干脆用 VS Code 的内置终端这当然可以。但如果你是想长期把 Claude Code 当作日常编程助手来用我还是建议先装一个 Windows Terminal。原因很简单它支持多标签页开多个项目目录互不干扰。字体渲染和色彩兼容性更好Claude Code 输出的高亮代码块、表格不会乱掉。快捷键和复制粘贴体验接近 Linux 终端用惯之后回不去。Windows Terminal 在 Microsoft Store 里直接搜就能装。装好之后把默认终端软件改成 Windows Terminal后面所有操作统一在一个地方完成。1.4 Git 安装Claude Code 的隐形依赖Claude Code 本身不绑定 Git但它的核心工作场景配合 Git 仓库是最好的。比如它查看你的代码改动、生成提交信息、做 code review全部建立在 Git 元数据之上。如果你没装 Git功能直接少一大半所以安装教程里必须提这一笔。从官网下载 Git for Windows安装时注意三件事默认编辑器选哪个无所谓反正命令行为主。“调整你的 PATH 环境”这一步选Git from the command line and also from 3rd-party software确保任何终端都能直接用git命令。换行符转换选Checkout as-is, commit as-is避免跨平台项目里 CRLF 导致一堆无意义的 diff。装完验证git --version到这里整体环境就绪了。2. 核心安装步骤一条 npm 命令解决环境准备好之后真正的安装过程其实简单到一句话npm install -g anthropic-ai/claude-code这条命令会从 npm 官方源拉取 Claude Code 的二进制包然后安装到全局 node_modules 目录同时在系统 PATH 里注册claude命令。安装过程通常在一两分钟内完成取决于网络状况。国内网络环境下npm 官方源偶尔会很慢这是正常现象。慢到实在离谱的时候可以临时切到国内镜像源npm config set registry https://registry.npmmirror.com装完建议把镜像源换回官方源或者干脆保持不变都行。这里没有对错之分只有稳定不稳定。我更建议先在官方源下试一次如果反复超时再切镜像毕竟有些 npm 包在镜像源上的更新会有延迟。2.1 安装完成后的验证方式安装结束后不要急着关闭窗口先确认安装结果。输入claude --version如果能看到版本号比如1.0.x或更新的版本就说明安装成功。如果提示找不到命令大概率是 npm 的全局 bin 目录没加进 PATH。查一下 npm 的全局目录npm prefix -g这个路径下的 bin 目录需要出现在系统 PATH 里。在 Windows 上常见的是C:\Users\你的用户名\AppData\Roaming\npm手动把这一行加进环境变量后重新打开终端就能使用claude命令了。2.2 为什么推荐全局安装而不是 npx很多人新手教程里会写npx claude或者npx anthropic-ai/claude-code这样的用法。npx 的好处是不污染全局环境每次调用临时拉取包。但它的缺点也很明显每次首次运行都要重新解析包冷启动慢。如果项目里有多个本地依赖版本混乱npx 的行为会变得不可预测。Claude Code 是要高频使用的工具不是偶尔跑一次的小脚本全局安装是更稳定的选择。所以我个人强烈推荐npm install -g这种全局安装方式。2.3 npm 安装报错时的最常见原因如果安装过程中报错你可以按照优先级从高到低排查这几个方向错误类型一权限问题Windows 上偶尔会碰到 npm 无法写入全局目录的情况。多数时候是因为使用了公司电脑或者 Node.js 安装目录被设在了C:\Program Files这种需要管理员权限的位置。不要急着用管理员身份运行终端那是治标不治本。更好的方案是修 npm 的全局路径到用户目录npm config set prefix $env:APPDATA\npm设置完之后重新安装问题通常就解决了。错误类型二证书或网络错误UNABLE_TO_VERIFY_LEAF_SIGNATURE、GET https://registry.npmjs.org超时这类报错大概率是网络环境干扰了 npm 的请求。可以先用镜像源临时绕过同时检查一下系统的防火墙是不是拦了 Node.js 进程的对外访问。错误类型三缓存污染这个比较阴间明明网络正常权限正常但 npm 反复在同一位置卡住。建议先清缓存再重试npm cache clean --force然后再执行安装命令。3. 首次启动与登录授权把通道打通安装完成只是一个开始真正的关键环节是登录授权。输入claude回车你会看到欢迎界面和一条登录提示。3.1 用官方登录流程拿到授权首次运行会弹出一个浏览器窗口跳到 Claude 的授权页面。你需要在浏览器里确认允许 Claude Code 访问你的账号然后等终端提示“登录成功”。整个过程有点像你平时用 GitHub 授权第三方应用本质上也是一个 OAuth 登录。如果你运行的是无桌面服务器版本或者浏览器没有正常弹出Claude Code 还提供了一种手动授权方式它会显示一个 URL你手动复制到任意设备的浏览器里打开输入代码完成授权。这个备用路径在 Windows 上很少用到因为本机浏览器几乎一定能弹出但知道有这个东西心里踏实。3.2 登录方式之间的区别这里有个容易搞混的地方。Claude Code 支持两种账号模型Claude.ai 账号订阅制你的 Claude Pro / Max 订阅额度在终端里直接可用。API 计费使用 Anthropic API 密钥按 token 计费适合深度调用或自动化场景。安装教程里一般不强调这一点但实际使用中差别巨大。如果你用的是 Claude.ai 订阅登录时按“Continue with Claude.ai”这条线走如果注册的是 Anthropic Console 的 API 账号则选 Console 线路。选错会导致登录后显示“没有可用额度”或“需要添加结算方式”之类的问题。我个人日常主力是 Claude.ai 订阅因为终端里的交互式使用对 token 消耗很大API 按量计费一下子烧掉不少。订阅制对高频使用的人来说更划算。3.3 登录完成后先跑一个最简单的任务登录成功之后别急着把它放进项目里。先在一个干净的目录下跑一个最小测试claude然后输入类似以下内容帮我确认一下当前运行环境并告诉我 Node.js 版本和操作系统版本。这是最直观的冒烟测试。如果它能正常回复、正常调用工具说明安装链路已经完整。这一步很重要因为它把环境变量、登录凭证、模型调用整个串了起来。一旦通了后面所有事情都好办。顺便说一句Claude Code 的首次启动会在用户目录下创建一个.claude目录用来存放配置文件、历史会话和授权信息。你不需要动它但看到它出现基本等于安装成功。4. 和 VS Code 组合把终端助手变成编码搭档安装好 Claude Code 之后很多人第一个问题就是我该怎么在日常干活时顺手用上它单独开一个终端窗口当然没问题但如果你的主力编辑器是 VS Code我建议直接把 Claude Code 跑在 VS Code 的内置终端里体验会舒服很多这也是热词里“vscode配置claude code”最常被搜的原因。4.1 为什么内置终端比独立终端更顺手在 VS Code 里打开一个项目后内置终端的当前路径会自动落在项目根目录。你直接敲claude它就能立刻看到整个项目结构、编辑器打开的标签页、甚至报错信息。这样 Claude Code 的上下文不是空的而是从你正在看的代码出发给出的建议更贴合实际。更妙的是 VS Code 支持多终端标签页。你可以一个标签页跑开发服务器另一个标签页跑claude互不干扰。需要 Claude 检查代码时切过去不需要时切回来即可。4.2 让 Claude Code 感知编辑器状态Claude Code 有一个很强的地方它能读取当前打开的文件和编辑器错误列表。在 VS Code 内置终端里运行时这个能力会自动生效不需要额外配置。实际效果是你可以直接问它“当前打开的文件里有什么问题”它会基于你正在看的代码给出回答而不是对着一整个仓库乱找。不过这要求你至少先建一个 Git 仓库。在 VS Code 中打开一个新目录后先执行git init原因很简单Claude Code 主要通过git diff和git status来理解代码变化。没有 Git 仓库它就只能凭目录里的文件做静态分析能力弱很多。4.3 .claude 目录和项目级配置在你的项目根目录下可以手动创建一个.claude文件夹里面放settings.json来做项目级配置。这个文件可以定义可用的工具开关自定义命令别名输出格式偏好禁止使用的工具列表比如我不想让它在某些目录里自动搜索就可以写{ permissions: { deny: [Read, Glob, Grep] } }不过新手不建议一上来就配置这个先用默认配置跑一星期等你对哪些操作会触发权限提示有感觉了再回头调。4.4 配合 Git 看变化的日常流程我现在最常用的一个工作流是这样的改完一段代码还没 commit。切到内置终端执行claude。直接输入“看一下当前改动帮我 review 一下有没有潜在问题。”它会自动执行git diff把改动从头到尾过一遍然后给你指出问题点。这套流程用顺之后你会发现很多低级 bug 在 commit 之前就被拦下来了。比写完再交给测试强太多。5. 新手最容易踩的坑真实排查过程还原我把这段时间在 Windows 上折腾 Claude Code 遇到的坑和用户反馈最多的问题集中列出来。每个坑都是真实的不是网上抄来的有些问题你能复现有些可能是版本更新后已经修复但理解排查思路比背答案重要。5.1 PowerShell 执行策略拦截了 npm 脚本现象安装命令跑到一半报错npm error: script postinstall cannot be run because the execution policy is restricted根因Windows PowerShell 默认执行策略是 Restricted只允许运行系统签名过的脚本。npm 包安装过程中的 postinstall 脚本属于任意脚本直接被拦。排查链路我一开始以为是 npm 权限问题换用户目录重装没解决。又以为是 Node 版本太低升级之后还是报同样的错。最后把报错信息完整读了一遍才发现它说的是“execution policy”。解决方案Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这个命令只影响当前用户不影响系统全局。RemoteSigned的含义是本地创建的脚本可以运行从网络下载的未签名脚本会被拦截。这是个人开发机上的安全且实用的策略不用改成 Unrestricted 那种完全放开的模式。需要说明的是这个命令只影响 PowerShell 对脚本的决策不影响你执行npm install -g本体因为 npm 本身是 node 进程不是 PS 脚本。真正被限制的是脚本加载阶段。5.2 安装成功后 claude 命令找不到现象npm 显示安装成功但输入claude --version提示“无法识别”。根因npm 的全局 bin 目录没在系统 PATH 环境变量里。排查过程先执行npm prefix -g看全局目录发现因人而异。在 Windows 上如果是默认 Node 安装路径一般是C:\Users\你的用户名\AppData\Roaming\npm但这个目录不一定被加进 PATH。打开“系统属性 → 环境变量”手动把该路径追加到 Path 变量里即可。补充说明改完环境变量后必须重新打开终端窗口因为已经打开的终端窗口不会自动刷新环境变量。第一次查不到命令时我差点以为安装失败了结果只是没重开窗口。5.3 安装卡在“preparing”或者进度条半天不动现象npm install 命令执行后长时间停在类似“prepare”阶段的提示。根因npm 正在解析依赖树或者网络源延迟。Claude Code 虽然最终产物体积不大但它的依赖链不算少首次安装需要拉取几十个包网络不好时确实慢。解决方案先等 2 到 3 分钟。如果还是不动切 npm 镜像源后重试。同时可以打开 npm 的详细日志来观察它在干什么npm install -g anthropic-ai/claude-code --loglevel verbose看到http fetch GET 200这类输出就说明网络是通着的只是速度慢。如果全是ETIMEDOUT那才需要换源。5.4 登录时报错“Something went wrong”现象点击授权链接后浏览器报错或者终端提示授权状态异常。根因大部分是浏览器缓存或某个中间跳转链路的问题。排查链路我第一次遇到时直接重试没用。后来用无痕窗口打开授权链接成功。说明是浏览器缓存了旧的登录态干扰了授权跳转。解决方案换无痕窗口、清浏览器 cookie或者直接在终端里执行claude login重新走一遍。登录之后一切正常。5.5 输出里的中文乱码或表格错位现象Claude Code 输出的中文正常但代码块、表格在某些终端里显示错位。根因Windows 传统终端的安全缺陷历史遗留问题对 Unicode 字符宽度计算不准确导致全角字符和半角字符混排时对不齐。解决方案换 Windows Terminal或者在 VS Code 内置终端里运行。这两个终端的字体渲染和字符宽度处理都好得多基本不会出现错位。如果你用的是老旧的 cmd 窗口出现错位不要太惊讶换个终端即可。6. 升级、卸载与清理打理是一辈子的活Claude Code 的迭代速度非常快基本上一个月能用上好几个版本。所以学会安装还不够升级和卸载也是完整使用闭环的一部分。6.1 如何平滑升级升级方式和安装完全一致npm install -g anthropic-ai/claude-codelatest升级不会影响到已经保存的授权信息也不需要重新登录。它会保留你的历史会话和项目配置。实际执行升级时唯一要注意的是别在 Claude Code 会话内部执行这条命令否则会占用文件锁。退出来在普通终端里执行再重新进入即可。检查当前版本和最新版本claude --version npm view anthropic-ai/claude-code version两者对比就能知道有没有新版本可升。6.2 完整卸载和配置清理如果你决定彻底不用了卸载命令是npm uninstall -g anthropic-ai/claude-code但光有这一步还不够。Claude Code 还会在用户目录下留下以下内容C:\Users\用户名\.claude配置文件、会话历史、授权信息如果用过项目级配置每个项目下的.claude文件夹卸载时是否删除这些取决于你的目的。如果只是暂时不用留着没坏处如果你打算彻底清理手动删除~/.claude目录即可。我个人的建议是不急着删。真的想再体验时重新登录又要折腾一次不如保留目录直接重装 npm 包就能接着用。6.3 版本回退方法有时候新版有问题想退回旧版也是标准操作npm install -g anthropic-ai/claude-code版本号比如npm view anthropic-ai/claude-code versions --json查看历史版本列表选一个你想锁的版本安装即可。6.4 多设备同步配置Claude Code 的一些配置是分散的你在一台 Windows 上改的配置不会自动同步到另一台机器。如果你有两台工作机可以考虑把~/.claude/settings.json放进自己的同步盘或者用 Git 仓库管理。但注意同步配置时不要同步授权凭证相关的文件那些是每台设备单独生成的拿到别处也没用。这个点看着小但真遇到“这台机器能跑那台不能跑”的困惑时配置不一致是首要怀疑对象。7. 我在 Windows 上使用 Claude Code 半年后的几句实话最后说点安装教程以外的东西。安装本身是个一次性动作真正影响体验的是你愿意花多少时间把工作流打磨顺。我在 Windows 上用了半年最大的三点感受是第一终端里的 AI 助力和网页版完全是两种东西。网页版适合聊天、写长文而终端版适合干工程活。它会自动读取目录结构、文件内容、Git 状态给出的建议像是团队里一个很熟悉代码库的同事在旁边说话而不是一个通用问答机器人。第二Windows 上的体验差异主要是终端环境造成的不是 Claude Code 本身造成的。只要把 Windows Terminal、Git、Node.js 这三样准备好体验和 macOS 上的差距很小。如果你还在用老式 PowerShell 窗口或者 cmd先把终端升级了再谈其他优化。第三别怕权限提示但要认真看了再放行。Claude Code 在操作文件、运行命令前都会征求你的同意。很多人觉得麻烦直接给了一揽子授权。在个人项目上无所谓但如果有真实敏感或生产环境代码请务必逐个确认它在做什么给的权限就要去维护这个限制。装好的第一天你可能只会让它写点小函数用了一周你可能开始让它重构整个模块用了一个月你可能会发现自己已经离不开claude这个命令了。希望这篇文章能帮你在这个月少走一点弯路。