没伞请奔跑i如果你和我一样，主力开发机是 Windows，又想在终端里用上 Claude Code，大概率会先搜一下“Windows安装claude code”这类关键字，然后照着某条命令开始敲。我当初也是这副状态：node -v 先测版本，紧接着 npm install -g @anthropic-ai/claude-code，觉得三分钟就能收工。结果问题一个接一个来：PowerShell 说不允许运行脚本，终端里中文全变方块，好不容易启动了又碰到 “is not a model” 的报错，最气人的是查了一圈资料，发现很多教程默认你在 Linux 或 macOS 上操作。
这篇文章把我从零装到顺手用的完整过程、以及每个坑背后的原因都交代一遍，给还在折腾的 Windows 用户省点时间。不管你是第一次接触命令行工具的新手，还是已经被各种报错搞到头皮发麻的老手，照着下面这几步走，基本可以少走大半弯路。
1. 先把安装路径想清楚：Windows下的三种跑法
1.1 它本质是个Node.js CLI，不是双击安装的桌面软件
Claude Code 官方的运行形态是一个命令行工具，底层依赖 Node.js，通过 npm 全局安装。很多 Windows 用户一上来就找“exe 安装包”或者“桌面版客户端”，这是第一层误区。它没有图形安装向导，真正的“桌面端体验”靠的是 VS Code 插件或者 IDE 集成面板，背后调用的还是同一个命令行工具。
搞清楚这一点，后面所有步骤都顺了。你装的其实是一组 JavaScript 文件加一个入口命令，入口命令就是 claude。它跟你在 Linux 服务器上装的那套东西没有本质区别，区别只在于 Windows 的终端环境、路径规则和脚本执行策略要额外处理一下。别被“命令行工具”四个字吓到，本质上它和你平时用 npm 装个 http-server 是一样的操作。
1.2 原生Windows、WSL、编辑器插件三种跑法对比
我在 Windows 上实际试过三种跑法，各有各的适用场景，先列个表格看清楚再选，不要一上来就照抄别人的方案。
| 跑法 | 安装方式 | 适合谁 | 注意点 |
|---|---|---|---|
| Windows 原生 + PowerShell | npm 全局安装 | 主力就是 Windows，写前端、脚本、通用开发 | 会遇到执行策略、中文乱码、路径分隔符问题 |
| WSL（Windows 子系统） | 在 Ubuntu 里装 Linux 版 Node 和 CLI | 经常要连 Linux 服务器、依赖 bash 脚本 | 配置跟 Windows 原生不互通，跨盘访问慢 |
| VS Code 插件 | 扩展市场安装，自动识别 CLI | 主要想边写代码边让 AI 改代码 | 插件底层还是依赖 npm 装好的 CLI |
先说结论：如果你平时就在 Windows 终端里写前端、写 Python 脚本，图省事，直接用“原生 + PowerShell”这条路。Claude Code 对 Windows 原生的支持已经很成熟，该踩的坑都有解。如果你日常开发跟 Linux 服务器强相关，经常要处理 ssh、grep、awk 这一套，那 WSL 里装 Linux 版更顺手，命令能跟服务器保持一致。至于 VS Code 插件，它不是“另一套 Claude Code”，而是同一个 CLI 的图形外壳，所以哪怕你主要用插件，也建议把命令行版装好。
1.3 我的选型建议
我自己的选择是原生安装为主，VS Code 插件为辅，WSL 当成备用环境。
原因很简单：我大部分项目都在 Windows 目录下，原生安装离代码最近，启动速度最快，不需要经过 WSL 的文件系统转换层。遇到需要在服务器上复现的问题，我再切到 WSL 或者直接连远程机器。你要是问“装一个够不够”，答案是够，但 WSL 里有 Linux 版也没坏处，只是要记住两边配置不互通——这个坑我后面专门讲。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：Node版本、终端和PowerShell策略
2.1 Node.js版本选择与安装要点
Claude Code 对 Node.js 版本有要求，官方要求 Node 18 及以上。我这里的建议是别卡着 18 用，直接上 20 LTS 或者 22 LTS。原因很现实：Claude Code 迭代快，npm 依赖树里不少包已经开始要求 Node 20 以上的特性，你装个 18 虽然能跑，但升级几次之后容易遇到依赖兼容问题，与其那时候再折腾，不如一开始就装个稳的。
安装 Node.js 时有几个细节，踩过坑的人都知道有多重要：
- 去官网下载 LTS 版安装包，不要图新鲜下 Current 版。
- 安装向导里务必勾选“Add to PATH”，这一步漏了，后面
node命令直接“不是内部或外部命令”。 - 装完一定要重开终端再执行
node -v，终端不会自动刷新环境变量。 - 如果你机器上本来就有多个 Node 版本（比如老项目用的 v14），别急着卸载，先装个
nvm-windows做版本管理，再在 nvm 里装一个新的 LTS 版本。
我用的是 nvm-windows 管理的 Node 环境，平时默认走 v22，需要跑老项目时切到 v18。Claude Code 装在 v22 下面，各版本互不干扰。如果你只有一套 Node，也没必要为这个工具单独引入 nvm，别过度工程化。
2.2 Windows Terminal + PowerShell 7 值得单独配一下
Windows 自带的 cmd 和 Windows PowerShell 5.1 能用，但体验差距明显。Claude Code 的输出有颜色、有表格、有交互式控件，老终端渲染这些东西很容易出问题。强烈建议装 Windows Terminal，Win11 自带，Win10 可以从商店免费装；然后把 PowerShell 7 也装了——注意，PowerShell 7 是独立安装的，不是系统自带的 Windows PowerShell 5.1，两者可以共存。
为什么要费这个劲？两个原因：一是 Windows Terminal 对 Unicode 和 UTF-8 的支持好得多，中文乱码的概率大幅下降；二是它的主题、字体、快捷键配置跟 VS Code 内置终端一脉相承，你在这个终端里养成的习惯，切到 VS Code 里完全无缝。装完以后，把默认配置文件改成 PowerShell 7，字体选 Cascadia Mono 或者支持中文的字体，后面跑 Claude Code 会舒服很多。
2.3 检查PATH和执行策略，排除最常见的启动失败
环境准备阶段，有两个问题几乎每个 Windows 用户都会撞上，提前排查能省不少时间。
第一个是“node 不是内部或外部命令”。这个基本都是安装时没勾 Add to PATH，或者改过 PATH 后没有重开终端导致的。处理办法很直接：重装一遍 Node，确认勾选那一项；或者手动把 C:\Program Files\nodejs\ 加进用户 PATH。
第二个是“无法加载文件 ... claude.ps1，因为在此系统上禁止运行脚本”。这个报错我在 PowerShell 里第一次跑 claude 命令时准时出现。原因是 PowerShell 默认执行策略是 Restricted，npm 全局脚本安装时会生成一个 .ps1 包装器，PowerShell 出于安全考虑不许它执行。解决办法是在当前用户级别放开限制：
bash复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
注意，这里不推荐改成 Unrestricted。RemoteSigned 的意思是本地脚本可以运行，从网络下载的脚本必须有签名，对开发机来说够用而且更安全。改完执行策略后重新打开终端，claude 命令基本就能起来了。
2.4 npm源与网络环境的现实问题
npm 默认官方源在国内某些网络环境下安装速度很慢，甚至超时失败。这一步我通常会先把 registry 切到国内镜像，命令很简单：
bash复制npm config set registry https://registry.npmmirror.com
这只是一个镜像源，不改工具行为，只加快包下载速度。换完之后可以用 npm config get registry 确认。
顺便说一句，Claude Code 安装完成后，首次登录和调用模型服务都需要走官方认证流程。如果你的工作网络有额外的访问限制，请按你自己环境的合规要求来处理，不要试图绕过任何安全策略。我在这篇文章里只讲工具本身的安装和配置，不讨论网络访问层面的“特殊手段”。
3. 实战安装：从npm命令到首次对话
3.1 安装命令、版本确认与升级
环境准备好之后，安装本身其实就一条命令：
bash复制npm install -g @anthropic-ai/claude-code
全局安装的好处是 claude 命令在任意目录都能直接用，不需要每个项目单独装。装完以后先验证版本：
bash复制claude --version
如果能看到版本号，恭喜，核心安装已经成功。如果提示找不到命令，先重开终端，再不行就检查 npm 全局 bin 目录是否在 PATH 里。查看全局安装路径可以用：
bash复制npm root -g
后续升级也简单，Claude Code 发版挺勤的，我基本每两周就会升一次：
bash复制npm install -g @anthropic-ai/claude-code@latest
如果你不想每次都被新版本打断工作流，可以指定版本安装，比如 npm install -g @anthropic-ai/claude-code@2.0.x。但我的建议是有新版就升，因为这个工具修 bug 的速度和加功能的速度一样快，旧版本容易遇到一些已经修复的型号识别问题和服务端兼容问题。
3.2 首次启动：账号登录还是API密钥
安装完成之后，在任意目录敲 claude，第一次会进入登录流程。这里有两种认证方式，取决于你手上的账号类型。
第一种是 OAuth 登录。终端会输出一个授权链接，浏览器打开后登录你的 Anthropic 账号，授权完成后终端自动进入会话。这种方式适合订阅类账号，会话历史和个人配置跟着账号走，换机器以后重新登录就能恢复原样。
第二种是 API 密钥方式。在登录流程里选择 API Key，然后把 Anthropic 控制台生成的密钥填进去。密钥通常会要求配置为环境变量 ANTHROPIC_API_KEY。我个人的习惯是：密钥只放在用户环境变量里，绝不写进项目代码，也不在命令行明文传递。
在 Windows 上设置用户环境变量，可以用系统设置里的“编辑账户的环境变量”，也可以用 PowerShell 一次性设置：
bash复制setx ANTHROPIC_API_KEY "你的密钥"
注意 setx 只对之后新开的终端生效，当前终端要继续跑的话，得先重开窗口。
3.3 在当前项目里跑起来：claude命令的基本用法
登录成功后，进到一个实际项目目录，比如：
bash复制cd D:\projects\my-app
claude
这个工具会自动扫描当前目录的文件结构、Git 状态、依赖关系，然后进入交互式会话。在交互界面里可以像聊天一样提需求，也可以让它直接改代码。我最常用的几个命令参数列一下：
claude：进入交互式会话claude "帮我解释一下这个报错"：直接一次性提问，不进入长会话claude --continue：继续上一次会话claude --model 模型ID：临时切换模型claude --dangerously-skip-permissions：跳过所有权限确认，适合完全信任任务的批处理场景，慎用
进入会话后，内置命令以 / 开头，比如 /help 查看帮助，/status 查看上下文用量，/quit 退出。第一次跑的时候建议先 /help 扫一遍，Windows 用户容易忽略权限确认的逻辑——它默认在操作文件前会问你“是否允许”，不要一上来就全部拒绝，也不要无脑全允许，先看它想做什么再决定。
3.4 配置文件和目录结构
Claude Code 的配置分几个层级，Windows 下的默认路径要记清楚。用户级全局配置在：
text复制C:\Users\你的用户名\.claude\
这个目录下面有 settings.json 存放全局配置，projects\ 存放各项目的会话记录。项目级配置则放在项目根目录的 .claude\settings.json。
三档配置优先级从低到高是：用户级全局配置、项目共享配置、项目本地配置（.claude\settings.local.json）。团队协作时，项目共享配置可以入库，本地配置要加入 .gitignore。这个目录结构别看它不起眼，后面调权限、调模型、配技能包全部要跟它打交道。
4. Windows专属的坑：乱码、路径和编辑器联动
4.1 中文乱码：代码页与UTF-8的博弈
Windows 上跑 Claude Code，最烦的不是安装失败，而是安装成功以后中文乱码。终端里中文变成方块、问号或者一团乱码，看着非常崩溃。这个问题的根源在于 Windows 传统控制台的代码页和进程输出编码不一致。
Claude Code 输出的是 UTF-8 字节流，而 Windows 老式控制台默认代码页可能是 GBK（代码页 936），两边对不上，自然乱码。解决办法有几个，按推荐顺序来：
- 用 Windows Terminal，它默认就是 UTF-8，乱码概率大幅降低。
- 老式 cmd 里临时切换代码页，执行
chcp 65001，把当前窗口代码页切到 UTF-8。 - Windows 系统区域设置里勾选“使用 Unicode UTF-8 提供全球语言支持”，这个需要重启，而且会全局改变系统编码，影响其他老软件，不建议为这一个工具去动系统级设置。
- 检查终端字体，确保用的是支持中文的字体。
我实测下来，最省心的组合是 Windows Terminal + 默认字体，基本不用额外设置。如果你还在用老 cmd，装上 Windows Terminal 比调系统设置划算得多。
4.2 在VS Code里用Claude Code的两种姿势
VS Code 和 Claude Code 的联动方式有两种，很多人搞混。
第一种是官方扩展。在 VS Code 扩展市场搜“Claude Code”，装好后命令面板搜索 Claude Code，它会自动识别已经通过 npm 安装好的 CLI，打开一个侧边面板或者终端面板。这种方式适合想在一个界面里同时看代码和对话的人。
第二种是直接在 VS Code 内置终端里跑 claude 命令。我更喜欢这种方式，因为 AI 能通过终端输出直接“看到”报错信息，方便它分析问题。而且内置终端本质上就是 Windows Terminal 的内核，配置好的字体、主题、UTF-8 支持都能继承。
如果你装了扩展但提示找不到 CLI，多半是因为 VS Code 的终端环境变量和系统不一样。重开 VS Code，让它重新加载环境变量；还不行就检查 VS Code 设置里是否有自定义的 terminal.integrated.env.windows，这一步会把 PATH 覆盖掉。
4.3 中文路径、空格路径的处理
Windows 用户名经常是中文，项目路径也可能带空格。这种情况下 Claude Code 多数时候能正常工作，但在一些工具链的边界会踩坑。我自己遇到过的：让 Claude Code 去调用某个构建工具时，构建工具传参没有正确处理路径，导致带空格的目录被拆成两个参数。
处理原则有三条：
- 项目目录尽量用英文路径，比如
D:\projects\my-app，不要放在中文用户名下面的一级目录。 - 涉及文件路径的手动操作，用双引号包裹整个路径，比如
claude "分析 D:\projects\my app\src"。 - 不要把中文文件名直接作为参数传给工具链底层操作，遇到编码边界容易出问题。
特别是公司电脑用户名是中文拼音加汉字混合的，最好把项目放到某个纯英文目录下，比如 D:\work\。这不是 Claude Code 的问题，是 Windows 生态老毛病，只是这个工具更容易触发而已。
4.4 启动报错速查表
把常见启动报错整理成一张表，方便直接对照排查。
| 报错信息 | 可能原因 | 解决方法 |
|---|---|---|
| node 不是内部或外部命令 | Node 没装好或 PATH 没配 | 重装 Node 并勾选 Add to PATH |
| 禁止运行脚本 | PowerShell 执行策略受限 | Set-ExecutionPolicy RemoteSigned -Scope CurrentUser |
| Cannot find module | Node 版本过旧 | 升级到 Node 20+ LTS 再装 |
| 529 | Anthropic 服务端过载 | 不是本地问题，过会儿重试 |
| xxx is not a model this version of Claude Code recognizes | 模型名不被当前版本识别 | 用 --model 指定支持的模型 ID |
| EPERM 或 EACCES | 权限不足或杀软拦截 | 管理员身份重试，或配置用户级 npm 前缀 |
5. 把Claude Code调成自己顺手的样子
5.1 用 claude config 管理设置
Claude Code 提供了一套配置命令，类似 git config 的交互方式：
bash复制claude config list
claude config get theme
claude config set theme dark
更直接的方式是编辑 settings.json。我的用户级配置文件长这样：
json复制{
"theme": "dark",
"verbose": true,
"permissions": {
"allow": [
"Read",
"Glob",
"Bash(npm run *)",
"Bash(git *)"
]
}
}
需要提醒的是，每个版本的配置字段名可能会有调整，不要盲目照抄网上的配置片段。最稳的办法是先用 claude config list 看当前版本支持哪些配置项，再决定改哪里。Windows 用户特别注意 permissions 里的 Bash 权限，你允许的命令会直接影响 Clance Code 对项目的操作范围，别把 Bash(*) 当成默认值，除非你明确知道自己在做什么。
5.2 权限模式、模型选择与输出格式
权限模式是刚上手时最容易困惑的部分。默认情况下，Claude Code 每执行一个敏感操作都会弹确认，这保证了安全，但也会让你手动点很多次。如果只是让它在项目里读文件、写代码，可以先在权限配置里放行常见操作，比如允许读文件、允许执行 npm run、允许执行 git 命令。等需要更激进的重构时，再临时加 --dangerously-skip-permissions。
模型选择方面，我日常使用默认模型，它会自动在能力和速度之间平衡。碰到复杂的架构分析、跨文件重构，再手动切到更强的模型，用 --model 参数指定。聊胜于无的优化是，把输出格式设为 JSON，适合后续自己写脚本包装：
bash复制claude --output-format json "分析这个项目的技术栈"
在 Windows 上结合 PowerShell，可以把 JSON 输出直接管道给 ConvertFrom-Json 做进一步处理，这算是把 Claude Code 当自动化工具用的进阶玩法。
5.3 接入自定义API网关时最常见的模型名报错
这一节说一个社区里很常见的诉求：把 Claude Code 接到团队自建的 API 网关，或者接第三方兼容服务。做法并不神秘，核心是设置环境变量 ANTHROPIC_BASE_URL 指向兼容 Anthropic 消息协议的服务地址。
但做这一步之后，高频出现的报错就是：
text复制"deepseek-v4-pro" is not a model this version of Claude Code recognizes
这个报错的本质是：Claude Code 当前版本内置了一份模型名校验列表，你填的模型 ID 不在它认识的范围内，所以直接拒绝。解决方案有几个方向：
- 用
--model参数显式指定模型 ID，绕过交互菜单的默认选择。 - 通过环境变量
ANTHROPIC_MODEL设置一个网关支持且官方列表里存在的模型 ID。 - 升级 Claude Code 版本，新版本通常会放宽模型名校验范围。
需要注意，如果网关只兼容 Anthropic 的接口格式，但模型本身不是 Claude 系列，输出质量和行为模式可能跟预期有偏差，这属于工具链本身的技术边界。另外，接入第三方网关时，建议先确认服务端是真的兼容 Anthropic 消息协议，别光看宣传。涉及敏感代码和公司内部数据时，要遵循公司的数据安全要求，别为了图方便把代码临时指向来路不明的外部端点。
5.4 Skills技能包：把工具链沉淀到项目里
Claude Code 的 Skills 技能包机制，是我用了之后觉得最提升效率的功能。它的原理很简单：在项目里放一个 .claude/skills/技能名/SKILL.md 文件，用 frontmatter 声明技能的名称和描述，正文写清楚具体操作步骤。Claude Code 会在处理相关任务时自动加载这个技能包，按照里面的步骤执行。
比如我给自己 Windows 项目的构建流程写了一个技能包，内容大致是：先执行 npm run build，构建完成后去 dist 目录检查产物，然后执行 node scripts/verify.js 验证完整性。以前每次让 Claude Code 跑构建都要重新说一遍，现在它自动会按技能包走。
对 Windows 用户来说，技能包特别适合沉淀那些“只有自己团队才懂的 Windows 路径和命令”。比如某些老项目的构建脚本要指定 C:\tools\build.bat，这些约定写进 SKILL.md，以后任何人接手都不会再让 AI 猜来猜去。
6. 几天实测后的几条Windows心得
6.1 长时间任务与终端稳定性
Claude Code 处理大项目时，终端会长时间高频输出。在 Windows 下，Windows Terminal 比老式控制台稳定很多，但也不是绝对不出问题。我遇到过一次输出卡顿，滚动变得很慢，后来把终端的自动换行关掉，情况明显改善。
另外建议给 PowerShell 窗口设置一个合理的缓冲区行数。默认的缓冲区如果太小，长输出会把前面的内容挤掉，你想回看日志都找不到。在 Windows Terminal 的设置里把“缓冲区大小”调到 10000 行以上，对排查问题很有帮助。
长时间跑 AI 任务时功耗也不低，笔记本用户注意一下电池策略。我试过连续让 Claude Code 重构一个中型项目，一小时左右风扇狂转，电量掉得比平时快不少。
6.2 WSL与Windows原生之间的边界
如果你也走“原生为主、WSL 为辅”的路线，一定要记住一件事：WSL 里的 Claude Code 和 Windows 原生的 Claude Code 是两个独立安装，配置目录不互通。在 Windows 里配好的 API 密钥、settings.json、登录状态，WSL 里一概认不到。反过来也一样。
文件系统访问也是这样。从 WSL 里操作 /mnt/c/ 下面的 Windows 项目，速度明显比操作 WSL 原生目录慢；反过来，Windows 侧访问 WSL 文件要走 \\wsl$\ 这个特殊路径。我的原则是：项目在哪边，就在哪边装 Claude Code，不要跨区操作。特别是别在 WSL 里让 Claude Code 去扫描一个很大的 Windows 项目目录，那速度会让你怀疑人生。
6.3 多版本Node环境下的安装坑
用 nvm-windows 管理 Node 版本的坑，我差点被坑两次。nvm 切换 Node 版本之后，npm 全局包是跟着当前版本走的。你在 v22 下装了 Claude Code，切到 v18 之后，claude 命令很可能直接消失。
这不是 bug，是 nvm 的设计机制：每个 Node 版本有自己独立的全局 node_modules。解决办法是切换到目标 Node 版本后，重新执行一次：
bash复制npm install -g @anthropic-ai/claude-code
如果你经常在多个 Node 版本间切换，建议在终端配置文件或者 nvm use 命令后加一个重装全局包的提醒，不然你会发现“明明装好了怎么又没了”的情况反复发生。
6.4 团队协作：配置文件入库与忽略策略
最后聊一个容易被忽视的问题：.claude 目录应该怎么处理。我的建议是分清楚什么该进 Git、什么不该进。
应该入库的：
.claude/settings.json：团队共享的权限配置、模型配置。.claude/skills/：团队沉淀下来的技能包。
应该忽略的：
.claude/settings.local.json：个人本地的个性化覆盖。.claude/projects/：会话历史，每个人都不一样。- 用户级
C:\Users\你的用户名\.claude\下的任何东西，不要提交进仓库。
如果团队里有人误把整个 .claude 目录提交了，会让仓库里混入大量个人会话记录。轻则仓库膨胀，重则泄漏敏感的业务信息。在 .gitignore 里明确写上 .claude/settings.local.json 和 .claude/projects/，这点非常值得一上来就做掉。
最后分享一个我自己的小习惯：每次给 Claude Code 抛任务前，先用一句话讲清楚当前目录、用到的技术栈、想要的结果，再贴报错。Windows 下终端输出的报错往往带颜色和特殊字符，直接复制可能带上转义序列，建议先关掉颜色再复制，用 --no-color 参数或者设置环境变量，这样模型看到的是干净的纯文本，不容易被干扰。这个习惯救了我好几次，尤其是在处理乱码、路径、执行策略这类 Windows 专属问题时。