如果你最近在技术社区里逛应该没少刷到 Claude Code 这个词。它本质上是 Anthropic 官方推出的命令行 AI 编程助手能直接在终端里读你的项目代码、改文件、执行命令就像旁边多了一个随时待命的结对工程师。但绕了一圈你会发现网上的教程多半默认你在 macOS 或者 Linux 上操作Windows 用户照着敲完十有八九卡在第一步node 装好了npm install 跑完了输入claude却提示“不是内部或外部命令”。这篇文章我就把 Windows 上从零到能用的完整路径走一遍环境准备、安装、登录、配置、接入第三方模型、常见坑位全部按实操顺序来你照着敲就行。我默认你是一个会用鼠标打开设置、能复制粘贴命令的普通开发者不要求你懂什么底层原理。同时我会把每个步骤背后的原因讲清楚这样就算哪天命令变了你也能自己判断问题出在哪。1. 为什么 Windows 用户装 Claude Code 特别容易翻车1.1 Claude Code 到底是什么东西Claude Code 的形态和传统 IDE 插件不一样它是个命令行工具。你在终端里启动它之后它会以对话的方式和你交互你描述需求它分析当前目录下的代码给出修改建议或者直接动手改。它由 Node.js 编写通过 npm 全局安装所以本质上它的跨平台能力取决于 Node.js 的跨平台能力理论上 Windows 原生就能跑不需要虚拟机也不需要 WSL。但“理论上能跑”和“实际能跑”之间隔着一堆 Windows 特有的问题。这个工具的很多内部操作都基于 Unix 风格的路径和 shell 习惯比如用/拼接路径、用~表示用户目录、调用bash命令等。Windows 的默认终端 CMD 和 PowerShell 在行为上差异很大再加上环境变量、权限模型、编码方式全都不同这就导致同样的安装步骤在 macOS 上一步到位在 Windows 上能折腾出七八种报错。1.2 高频翻车点先有个心理预期根据我在 Windows 上反复安装、卸载、再安装的经验最容易出问题的集中在下面这些位置npm 全局安装目录没有被加到PATH导致claude命令找不到PowerShell 的执行策略默认限制脚本运行导致命令行工具启动时报错Node.js 版本太老或太新触发EBADENGINE引擎不匹配安装时使用了中文用户名或者带空格的路径导致权限和路径解析出错杀毒软件或 Windows Defender 把命令行工具的临时文件拦截启动后莫名其妙闪退。这些问题不是 Claude Code 独有的所有 Node.js 命令行工具在 Windows 上都会遇到只是 Claude Code 的功能面更大触发这些问题的概率也更高。理解这一点你后面排查起来就不慌。1.3 两条安装路线怎么选Windows 上装 Claude Code 有两条主流路线一条是原生 Windows 环境直接在 PowerShell 或 Windows Terminal 里跑另一条是先装 WSLWindows Subsystem for Linux在 Linux 子系统里跑。我的建议是如果你只是想在 Windows 上快速体验、应付日常开发原生路线完全够用如果你经常处理 Linux 服务器上的项目、依赖一堆bash脚本那 WSL 路线会让后面的体验顺畅很多。不过这篇教程主线是原生 Windows 路线因为你是多数派。WSL 路线我会在最后给出切换建议但不会展开太深避免你两条路都走了一半哪个都没配好。2. 动手前的环境准备2.1 先把终端换掉Windows Terminal PowerShell 7你如果还在用系统自带的 CMD 黑窗口我建议先花 10 分钟装一个 Windows Terminal。它可以从微软商店直接搜索安装免费功能强很多支持多标签页、支持 PowerShell 7、支持自定义字体和配色最关键的是它对 UTF-8 编码的支持比老终端好能少遇到很多中文乱码问题。装好 Windows Terminal 之后把默认配置文件改成 PowerShell。Windows 自带的 Windows PowerShell 5.1 也不是不能用但有个经典坑它默认把命令执行策略设为 Restricted虽然你手动执行claude不受影响但 Claude Code 在内部调用一些辅助脚本时可能会被拦。所以我更推荐装 PowerShell 7它默认执行策略更宽松而且对现代命令行工具兼容性更好。安装 PowerShell 7 同样在微软商店搜 PowerShell 就能找到或者用winget install Microsoft.PowerShell命令。装完之后在 Windows Terminal 的设置里把默认 shell 指到 PowerShell 7。这一步做完你的终端体验基本就达标了。2.2 Node.js别用“最新”要用 LTSClaude Code 是一个 Node.js 应用所以 Node.js 是必装项。很多人在这里踩坑是因为装了 Node 的最新版Current 版结果某些依赖还没跟上报一堆引擎警告。我试过用 Node 22 和 Node 20 LTS 跑 Claude Code后者明显更稳。推荐做法去 Node.js 官网下载 LTS 版本的 Windows Installer.msi 文件一路下一步。安装的时候注意看安装向导里有没有“Add to PATH”选项默认是勾上的确保它是勾选状态。这个选项会把 Node.js 的安装目录写进系统环境变量后面npm命令才能直接在任意位置使用。安装完成后重启终端执行两条命令验证node -v npm -v能看到版本号输出就说明 Node 没问题。如果你以后还想管理多个 Node 版本可以装 nvm-windows但这个不是必须的先跑通再说。2.3 Git不装也能装装了更省心Claude Code 本身不强制要求 Git但它在分析项目、生成 diff、提交代码时如果检测到 Git 环境行为会专业很多。而且很多 Windows 用户的终端问题其实出在没有 Git Bash 提供的 Unix 工具集。我不建议你为了装 Claude Code 特意去折腾 Git Bash但装一个 Git for Windows 基本是白赚的。安装 Git 时注意三个选项第一在“Adjusting your PATH environment”那一步建议选中间项 “Git from the command line and also from 3rd-party software”第二行尾转换那一步建议选 “Checkout as-is, commit as-is”避免 Windows 的 CRLF 行尾把项目文件搞乱第三终端模拟器那一步选 “Use Windows default console window” 更省心选 MinTTY 在某些终端组合下会有字体问题。3. 正式安装与首次登录3.1 npm 全局安装一条命令的事环境准备到位后打开终端执行npm install -g anthropic-ai/claude-code这里有几个要点。-g表示全局安装不是装在当前项目的node_modules里。全局安装的好处是你在任意目录下都能直接调用claude命令。npm 在 Windows 上的全局安装目录通常是%APPDATA%\npm这个目录的路径会被写进PATH但偶尔会有写入失败的情况这就是后面claude命令找不到的根源。安装过程可能需要一两分钟取决于网络状况。如果看到npm warn级别的输出不用紧张只要最后没有npm error并且出现了类似added xxx packages的字样就说明装上了。装完之后验证claude --version如果终端输出了版本号恭喜你安装这一步已经过了。如果提示claude 不是内部或外部命令去 6.1 节看解决方案。3.2 深入理解一下 npm 全局机制避免瞎猜我多解释一句为什么这条路这么别扭。Windows 不像 Linux 那样有统一的/usr/bin目录npm 全局安装会把可执行文件放在%APPDATA%\npm同时生成一个claude.cmd批处理文件终端之所以能找到claude靠的是PATH环境变量。Windows 对PATH的更新有个臭毛病已经打开的终端不会自动刷新你必须新开一个终端窗口才能读到最新的PATH。所以如果你安装成功但命令找不到先别急着重装先新开一个终端试试。很多问题就是这么解决的。3.3 首次启动与登录授权接下来在任意目录建议先建一个空文件夹做测试里运行claude首次启动会进入一个交互界面并提示你登录 Anthropic 账号。它一般会打开浏览器跳到授权页面你点授权之后终端里会提示你粘贴一个授权码。如果浏览器没有自动打开终端里会显示一个 URL手动复制到浏览器打开即可。登录成功后Claude Code 会在你的用户目录下生成一个~/.claude.json之类的配置文件记录登录状态、设置项、历史会话。这些文件是纯文本的 JSON后续你如果想手动改配置可以直接编辑它但我不建议新手这么干容易改坏。登录这一步如果卡住最常见的原因是网络无法访问授权页面。这种情况下你需要确认你的网络环境是否允许正常访问该服务这是网络环境层面的问题不是安装步骤的问题。按照你所在环境的合规网络策略处理好网络可达性之后再重新执行claude即可。由于网络限制属于环境差异不同地区、不同网络差异很大具体以你的实际网络环境为准。3.4 PowerShell 执行策略提前设置省得之后闪退Windows PowerShell 5.1 里执行一些来自互联网的脚本会触发执行策略限制。虽然我刚才建议装了 PowerShell 7但保险起见还是提前设置一下当前用户的执行策略Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令的意思是允许本地脚本运行远程下载的脚本必须带有效签名才能运行。选择Y确认即可。这是开发者在 Windows 上跑各种命令行工具的常规操作不会降低太多系统安全性。如果你完全不了解这是什么意思记住“照做”就行。4. 日常使用必配项VSCode、第三方模型、权限控制4.1 在 VSCode 里集成 Claude Code很多人的开发主战场是 VSCode纯命令行窗口虽然能用但对比代码上下文时总隔一层。Claude Code 官方提供了 VSCode 扩展在扩展商店里搜索 “Claude Code” 就能找到安装后可以通过命令面板启动。这个扩展本质上还是调用你已经安装好的 CLI 工具所以刚才的 npm 全局安装是前提。安装好扩展之后我建议你给终端面板单独绑一个快捷键比如Ctrl ~打开内置终端然后输入claude启动。这样你左手看代码右手在面板里和 Claude 交互效率比切到外部窗口高不少。VSCode 集成的另一个好处是Claude Code 读取当前目录文件时VSCode 的文件导航可以让你更直观地看到它改了哪些文件。配合git diff检查改动心里更有底。4.2 接入 DeepSeek 等兼容 API把默认模型换了Claude Code 默认调用 Anthropic 的 Claude 模型需要有效的 Anthropic 账号和 API 额度。如果你在账号或额度上有门槛或者你就是想试试别的模型社区里已经有人验证过一条可行路子通过兼容 Anthropic 协议的服务端点来切换模型。国内可用的 DeepSeek 就提供了 Anthropic 兼容接口可以在 Claude Code 里直接用。具体做法是设置两个环境变量然后再启动$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN你的DeepSeek密钥设置完之后运行claude这次它就不会要求你走 Anthropic 的登录授权而是直接用你配置的密钥和地址访问 DeepSeek 的模型。你可以用claude --model deepseek-chat或者启动后通过/model命令切换具体模型。我用过一段时间这个组合它的逻辑非常简单Claude Code 本身是一个客户端壳干活的是后面的大模型 API。Anthropic 的官方 API 走/v1/messagesDeepSeek 的兼容地址把同样的请求格式接到了自己的模型上。也就是说 Claude Code 负责读项目、整理上下文、执行命令而 DeepSeek 负责“思考”和生成代码。实际体验下来日常修 bug、补注释、写单元测试这类任务DeepSeek 的表现完全够用。需要注意几点。第一不同第三方服务的兼容程度不一样有些函数调用能力不完整可能导致 Claude Code 的部分工具功能失效第二密钥是敏感信息不要写进项目代码里更不要提交到 Git第三第三方服务按它们自己的计费规则收费自己心里有数。这套方案不是我发明的是社区验证过的通用做法具体接口地址和模型名称以 DeepSeek 官方文档为准。4.3 项目级配置与权限控制Claude Code 默认拥有你给它所在的目录的读写权限它改文件之前会先告诉你它要改什么但如果你不想每次都被询问可以创建一个项目级的配置文件在项目根目录建一个.claude文件夹里面放settings.json。举例{ permissions: { allow: [Read, Edit, Bash(npm run test)], deny: [Bash(rm -rf *)] } }allow是允许的操作列表deny是阻止列表。这个配置的好处是Claude Code 在遇到被允许的操作时不再逐个弹窗确认遇到被禁止的操作直接拒绝。我自己一般会把rm相关的危险命令放进deny因为命令行工具判断不了哪些文件是重要的。另外两个高频配置项claude config set -g autoUpdaterStatus disabled claude config set -g theme dark第一条关掉自动更新免得它在你不注意的时候升级导致行为变化第二条是主题想用默认可以不加。这些配置会写到~/.claude.json你可以随时查看和修改。5. 完整实操在 Windows 终端跑一个真实任务5.1 设计一个能检验安装成果的小任务光装上能启动还不算完你得实际跑一个任务确认链路畅通。我建议你先建一个测试目录里面放一个简单的 Python 文件或者任何你熟悉的语言比如一个故意写错的函数然后让 Claude Code 去修复并补一个单元测试。我这里的示例文件是一个计算平均数的 Python 脚本里面故意留了一个除零隐患当传入的列表为空时直接崩溃。任务指令就是让 Claude Code 修复这个问题并补一个边界测试。5.2 实际操作流程与现场记录耐心等待安装完成。目录结构test-project/ avg.pyavg.py内容故意写成def average(nums): return sum(nums) / len(nums)然后在终端里执行claude进入交互后输入指令修复 average 函数在空列表时的除零问题并补一个相应的单元测试。Claude Code 会先读取目录结构打印出它看到的文件然后给出分析它发现len(nums)为 0 时会抛ZeroDivisionError于是它建议在函数开头加一个空列表判断返回0或者抛一个更友好的异常。在你确认之后它直接修改avg.py然后创建test_avg.py里面包含对空列表、正常列表、负数列表三个用例的测试。修改完成后它会提示你运行测试的命令是python -m unittest test_avg.py或者直接问你是否允许它执行这个命令。如果你在权限配置里没有把这条命令加入allow它会弹窗请求确认你选择允许就行。测试跑完后你会看到类似OK的输出。这时整个链路就通了安装没问题、登录没问题、文件读写没问题、命令执行没问题、模型能力也没问题。这套验证做完你的 Claude Code 才算真正“能用”。5.3 实操过程的几个细节点我在这一步遇到过几个小问题顺手记一下。第一如果项目路径里有中文或空格某些模型生成命令时可能出错建议测试目录用英文路径第二Windows 的杀毒软件可能把 Python 的子进程调用拦掉导致测试命令没反应这时候去 Windows Defender 的“排除项”里把测试目录加进去或者临时关掉实时防护再试第三Claude Code 修改文件前会打印 diff你不用急着点确认先看一遍它准备怎么做这个习惯关键时刻能救你一命。如果你想要一个包含敏感操作的测试比如让它执行git init并提交代码注意确认 Git 已经安装并且在终端里执行过git config --global user.name和user.email设置不然提交时会报错。这也是一个常见坑Claude Code 本身没问题是你的 Git 环境没初始化。6. 高频问题排查与 Windows 专属坑6.1 安装后提示“claude不是内部或外部命令”这绝对是排第一的问题。原因是 npm 全局安装目录没有正确写进PATH或者你使用的终端还没刷新环境变量。先按顺序排查第一步新开一个终端窗口再跑claude --version。第二步如果还不行手动查看 npm 全局目录npm prefix -g输出一般是C:\Users\你的用户名\AppData\Roaming\npm。第三步打开系统环境变量设置在“Path”里添加这个目录把%APPDATA%\npm加进去保存后新开终端验证。注意直接改用户变量里的Path就够了不要动系统变量避免权限问题。如果你之前已经装过 Node.js这个路径多半已经在里面只是你没重开终端。6.2 npm 安装时报 EBADENGINE 或其他版本错误这个错误的意思是当前 Node.js 版本不满足某个依赖的要求。解决办法很简单下载 Node.js LTS 版本重新安装覆盖当前的安装。安装前可以先node -v看看当前版本如果是 18 以下的版本果断升级到 20 LTS。还有一种情况是安装过程中被安全软件拦截导致文件写入不完整。npm 报错信息里如果出现EPERM、EACCES这类权限字样多半是权限或杀毒问题。临时关一下 Defender 的实时保护再装一次装完再开回来。如果是公司电脑可能还有额外的安全策略那就需要联系管理员把%APPDATA%\npm加白。6.3 首次启动登录卡住几种表现浏览器没跳转、跳转了但授权页面打不开、粘贴授权码后报错。浏览器没跳转时终端里一般会给一个 URL手动复制到浏览器打开即可。页面打不开或授权码粘贴后报错基本是网络可达性的问题你需要确认当前网络环境下能否正常访问相关服务。各地区、各运营商到服务的连通性差别很大如果确实连不上先把网络问题解决再继续不要试图跳过登录因为 Claude Code 的很多功能依赖账号鉴权。另外注意令牌和会话信息会存在~/.claude.json里不要把这个文件删掉删掉等于重新登录。6.4 中文乱码或界面字符错乱Windows 终端老毛病了。Claude Code 输出彩色 ANSI 字符在旧版 Windows 10 的 CMD 或者默认代码页是 936GBK时很容易出现乱码。解决方法是把代码页切到 UTF-8chcp 65001或者直接改用 Windows Terminal把字体设置为Cascadia Mono并且在终端的设置里把默认代码页调成 UTF-8。还有一个偏方在系统设置里勾选“使用 Unicode UTF-8 提供全球语言支持”但这不是所有电脑都建议开我自己没开靠 Windows Terminal 就解决了。6.5 Windows 专属坑位杀软、UAC、长路径有个现象不是所有教程都会提Windows Defender 对命令行工具的实时扫描可能导致 Claude Code 在执行批量操作时明显变慢尤其是处理大项目时。如果你发现它读文件很慢可以先试试把项目目录加进 Defender 的排除项。UAC 弹窗则会影响需要管理员权限的操作Claude Code 本身不需要管理员权限运行所以如果你看到 UAC 弹窗反而要小心可能是有别的程序在搞事。长路径问题也值得一提。Windows 在某些设置下路径超过 260 个字符就无法访问而 Claude Code 处理大型项目时很容易生成超级深的路径。好在这几年 Windows 10/11 都支持通过注册表打开长路径支持你在“组策略”或注册表里启用LongPathsEnabled或者在你的应用里尽量把项目路径放浅一点比如C:\dev\project不要放桌面里套三层文件夹。6.6 如何彻底卸载卸载很简单一条命令npm uninstall -g anthropic-ai/claude-code卸载之后用户目录下的~/.claude.json和~/.claude文件夹不会自动删除。如果你确定以后不再用可以手动删掉里面存着会话记录和配置。如果你只是想在两个账号之间切换不用卸载退出登录再重新登录就行。另外VSCode 扩展也要单独卸载在扩展面板里点掉即可。一些补充建议因为这篇教程主要是 Windows 原生安装我再多说一句 WSL 路线。如果你决定主攻 WSL那么在 WSL 里安装的步骤和 Linux 基本一致先安装 Node.js 和 npm再执行npm install -g anthropic-ai/claude-code。好处是路径和命令行为都贴近线上服务器环境团队协作时不容易踩到跨平台差异。坏处是你需要在 Windows 和 WSL 两套文件系统之间来回切换对 Windows 新手不友好。我的建议很直接先在原生 Windows 上跑通体会一下它的实际能力和限制再决定要不要切到 WSL。工具是拿来干活的不是拿来折腾的。其实很多人在 Windows 上装 Claude Code最后发现最难的不是安装本身而是第一次启动时面对一个空白的命令行窗口不知道该干什么。我的建议是先把本文第 5 节的测试任务跑一遍用最小的代价建立信心。往后你会慢慢习惯这种工作流打开终端进入项目目录启动claude描述需求看 diff确认执行。这个流程在 Windows 上跑顺之后你的项目管理方式会变一个层次——你不用再记那些繁琐的测试命令和 git 操作只需要让 Claude Code 去思考和执行你负责判断它做得对不对。尝到甜头之后你自然就知道该怎么让它帮你做更多事了。