1. 为什么要在 Windows 上认真折腾 Claude Code

如果你平时主力开发环境是 Windows，又恰好想用 Claude Code 把日常的代码补全、重构、终端命令执行这些活儿串起来，那你大概率已经踩过一圈坑了。Claude Code 本身是个跑在终端里的 AI 编程助手，它能读你的项目文件、执行命令、改代码，甚至帮你跑测试。听起来很美好，但 Windows 和 macOS、Linux 的终端生态差异太大，直接照搬官方文档里的步骤，十有八九会卡在某个环节。

我前后在三台 Windows 机器上部署过 Claude Code，从 Win10 到 Win11，从原生 PowerShell 到 WSL2，踩过的坑包括但不限于：Node 版本不对导致安装脚本报错、终端权限不足导致守护进程起不来、环境变量配好了但新开的终端读不到、代理设置和公司网络策略冲突等等。这篇文章就是把这些经验一次性摊开，从安装、配置、终端选型到避坑优化，给你一条能直接抄的路径。

适合谁看？如果你是 Windows 上的前端、后端或者全栈开发者，日常用 VS Code 写代码，偶尔需要 AI 帮你处理一些重复性劳动，那这篇内容就是为你准备的。哪怕你之前没接触过 Claude Code，只要你会用命令行装个 Node.js，剩下的步骤我尽量写到“照着做就行”的程度。

2. 安装前的环境准备：别急着敲命令

2.1 Node.js 版本选择与安装方式

Claude Code 是通过 npm 分发的，所以 Node.js 是第一个硬性依赖。这里有个坑：不是所有 Node 版本都能跑。我实测下来，Node 18.x 和 20.x 的 LTS 版本最稳，Node 21 以上的奇数版本偶尔会出现依赖解析问题。如果你机器上已经装了 Node，先打开终端敲一下：

node -v npm -v

如果版本低于 18，或者你根本不确定之前装过什么，建议直接去 Node.js 官网下载 LTS 版本的 Windows Installer（.msi）。安装的时候有一个关键选项：Automatically install the necessary tools，这个勾上之后它会帮你装 Chocolatey 和 Python 等编译工具，虽然后面不一定全用得上，但省得你后面缺东西再回头补。

安装完成后，一定要关掉所有终端窗口重新开一个，否则 PATH 环境变量不会刷新。我见过太多人装完 Node 之后在旧终端里敲node -v发现还是旧版本，然后开始怀疑人生。

注意：如果你公司电脑有软件安装限制，可能需要管理员权限才能装 .msi。这种情况下可以考虑用 nvm-windows 来管理 Node 版本，它不需要管理员权限就能切换版本，但安装 nvm 本身还是需要一次管理员权限。

2.2 终端选型：Windows Terminal 还是 PowerShell 原生

Claude Code 在 Windows 上跑，终端的选择直接影响体验。我强烈建议用Windows Terminal，而不是直接开 PowerShell 或者 CMD。原因有三点：

第一，Windows Terminal 支持多标签和多窗格，你可以一边跑 Claude Code，一边开个标签看日志，不用来回切窗口。第二，它的字体渲染和 Unicode 支持更好，Claude Code 输出的一些特殊字符不会变成乱码。第三，Windows Terminal 可以很方便地配置启动时的默认 Shell，比如直接设成 PowerShell 7 而不是 Windows PowerShell 5.1。

如果你还没装 Windows Terminal，直接在 Microsoft Store 里搜就行，免费且安装很快。装完之后，在设置里把默认配置文件改成 PowerShell 7（如果你装了的话），或者至少确保是 PowerShell 而不是 CMD。

PowerShell 7 和 Windows 自带的 PowerShell 5.1 有什么区别？简单说，7 是跨平台的，基于 .NET Core，语法更一致，对 UTF-8 的支持也更好。Claude Code 在执行一些命令时，如果终端编码不对，中文路径或者特殊字符就会出问题。所以这一步别省。

2.3 Git 的安装与基础配置

Claude Code 很多功能依赖 Git，比如它要读你的项目状态、看 diff、提交更改。Windows 上装 Git 最简单的方式也是去官网下载安装包。安装过程中有几个选项值得注意：

• Adjusting your PATH environment：选 “Git from the command line and also from 3rd-party software”，这样 Git 命令在任意终端都能用。
• Choosing the SSH executable：如果你用 SSH 连远程仓库，选 “Use bundled OpenSSH”。
• Configuring the line ending conversions：选 “Checkout Windows-style, commit Unix-style line endings”，这是最兼容的做法。

装完之后，打开终端配置一下用户名和邮箱：

git config --global user.name "你的名字" git config --global user.email "你的邮箱"

这两条命令看起来简单，但如果你不配，Claude Code 在帮你提交代码时会报错，提示你身份未配置。我一开始就漏了这一步，结果 Claude Code 执行git commit的时候卡住，排查了半天才发现是 Git 全局配置没写。

3. Claude Code 的安装与首次配置

3.1 通过 npm 安装 Claude Code

环境准备好之后，安装 Claude Code 本身其实就一行命令：

npm install -g @anthropic-ai/claude-code

但这一行命令背后有几个容易出问题的地方。首先是网络，npm 默认走官方源，国内访问有时候会超时。如果你遇到安装卡住或者报ETIMEDOUT，可以临时切到国内镜像源：

npm config set registry https://registry.npmmirror.com

装完之后再切回来也行，或者你就一直用镜像源，问题不大。其次是权限，Windows 上全局安装 npm 包一般不需要 sudo，但如果你之前把 npm 的全局目录设到了系统盘某个受保护的位置，可能会报EACCES错误。解决办法是重新配置 npm 的全局目录到用户目录下：

npm config set prefix "C:\Users\你的用户名\.npm-global"

然后把C:\Users\你的用户名\.npm-global加到 PATH 环境变量里。这一步做完之后，重新开终端，再跑安装命令。

安装完成后，验证一下：

claude --version

如果能看到版本号，说明安装成功了。如果提示claude 不是内部或外部命令，那就是 PATH 没配好，回去检查 npm 的全局目录有没有加到系统环境变量里。

3.2 首次启动与认证配置

第一次运行claude命令，它会引导你完成认证。Claude Code 需要你登录 Anthropic 账号或者配置 API Key。如果你是在公司网络环境下，可能会遇到认证页面打不开的情况，这时候可以尝试用 API Key 的方式：

claude config set apiKey "你的API Key"

API Key 的获取方式这里不展开，你可以在 Anthropic 的开发者控制台里生成。配置好之后，Claude Code 会把凭证存在本地的一个配置文件里，路径大概是C:\Users\你的用户名\.claude\config.json。这个文件里除了 API Key，还有一些其他配置项，后面我们会细说。

注意：如果你所在的组织禁用了 Claude Code 的订阅访问，你可能会看到 “your organization has disabled claude subscription access for claude code” 这样的提示。这种情况下，你需要联系组织管理员确认策略，或者使用个人账号的 API Key。

3.3 在 VS Code 中集成 Claude Code

虽然 Claude Code 是终端工具，但它和 VS Code 的配合非常顺手。你可以在 VS Code 的集成终端里直接跑claude，这样它就能感知到你当前打开的项目路径。更进一步的玩法是装Claude Code for VS Code扩展，这个扩展会在侧边栏加一个面板，你可以直接在编辑器里和 Claude 对话，让它改代码、解释代码、跑命令。

安装扩展的步骤很简单：在 VS Code 扩展市场搜 “Claude Code”，找到官方那个，点安装。装完之后可能需要重启 VS Code，然后在设置里配置一下 API Key 或者登录账号。扩展装好之后，你在编辑器里选中一段代码，右键就能看到 Claude 相关的操作选项，比如 “Explain with Claude” 或者 “Refactor with Claude”。

我个人的习惯是：日常小改动直接在 VS Code 扩展里让 Claude 处理，涉及多文件重构或者需要跑终端命令的时候，切到 Windows Terminal 里用命令行版的 Claude Code。两者共享同一套配置，切换起来没有额外成本。

4. 核心配置项详解与优化

4.1 配置文件结构与关键参数

Claude Code 的配置文件默认在C:\Users\你的用户名\.claude\目录下，主要有两个文件：config.json和settings.json。config.json存的是认证信息和全局偏好，settings.json存的是项目级别的配置。如果你在项目根目录下建一个.claude文件夹，里面放settings.json，那这个项目就会用这套独立配置，不会影响全局。

几个我经常调整的参数：

• model：指定默认使用的模型。如果你有多个模型权限，可以在这里切换。
• maxTokens：控制单次响应的最大 token 数。设得太小，Claude 回答到一半就断了；设得太大，又浪费额度。我一般设 4096，够用。
• temperature：控制输出的随机性。写代码建议设低一点，比如 0.2，这样生成的代码更稳定。
• autoApprove：这个参数要小心。设成 true 的话，Claude 执行命令时不会每次问你，直接跑。方便是方便，但如果你在一个重要项目里，万一它跑了个rm -rf之类的命令，哭都来不及。我建议保持 false，或者只对特定命令开白名单。

4.2 终端命令执行权限与安全策略

Claude Code 最强大的功能之一是它能直接执行终端命令。比如你让它“跑一下测试”，它会自己敲npm test，然后把结果读回来分析。但这个功能也是双刃剑。Windows 上默认的 PowerShell 执行策略可能会阻止某些脚本运行，你会看到类似 “无法加载文件，因为在此系统上禁止运行脚本” 的报错。

解决办法是以管理员身份打开 PowerShell，然后执行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

这个命令的意思是：对于本地写的脚本，允许运行；对于从网上下载的脚本，需要有签名。这样既不会完全放开，也不会把正常操作挡住。

另外，Claude Code 在执行命令前会有一个确认步骤，它会显示要跑的命令，问你 Yes/No。如果你信任当前项目，可以按a表示 “always allow”，这样同类命令后续就不再问了。但我的建议是：在陌生项目或者生产环境相关的目录里，永远手动确认。我吃过一次亏，让 Claude 帮我清理临时文件，它理解成了删除整个 build 目录，幸好我多看了一眼确认提示。

4.3 网络与代理相关配置

如果你在公司内网，或者需要走代理才能访问外部服务，Claude Code 的请求可能会失败。它支持通过环境变量配置代理：

set HTTP_PROXY=http://你的代理地址:端口 set HTTPS_PROXY=http://你的代理地址:端口

在 PowerShell 里用$env:HTTP_PROXY="http://..."的写法。配完之后，Claude Code 的 API 请求就会走代理。但要注意，有些代理只支持 HTTP 不支持 HTTPS，或者需要认证，这些都要根据你的实际网络环境调整。

还有一个常见问题是 SSL 证书验证失败。如果你公司的代理做了 SSL 拦截，Claude Code 可能会报证书错误。这时候可以临时设置：

set NODE_TLS_REJECT_UNAUTHORIZED=0

但这是下策，因为关掉证书验证会降低安全性。更好的做法是把公司的根证书导入到 Node 的信任列表里，具体操作稍微复杂一点，这里不展开。

5. 实操流程：从零跑通一个完整项目

5.1 创建项目并初始化 Claude Code

假设我们有一个空目录my-project，想用 Claude Code 帮我们搭一个简单的 Node.js 项目。首先进入目录：

cd C:\Users\你的用户名\projects\my-project

然后启动 Claude Code：

claude

第一次在这个目录启动，它会问你要不要初始化项目配置。选 Yes，它会在当前目录下生成一个.claude文件夹，里面有个settings.json。这个文件里你可以预设一些项目级别的偏好，比如指定测试命令、代码风格等。

接下来，你可以直接跟 Claude 对话，比如输入：

帮我初始化一个 Node.js 项目，用 Express 框架，写一个 Hello World 接口。

Claude 会先分析当前目录，然后建议你跑npm init -y，接着安装 Express，然后创建index.js文件并写入代码。每一步它都会显示要执行的命令或要写入的内容，你确认之后它才动手。

5.2 让 Claude 执行终端命令并验证结果

项目初始化完成后，你可以让 Claude 帮你跑起来：

启动这个服务，然后测试一下接口是否正常。

Claude 会执行node index.js，然后可能用curl或者Invoke-WebRequest来测试接口。在 Windows 上，curl其实是Invoke-WebRequest的别名，行为跟 Linux 上的 curl 不完全一样。如果 Claude 用了curl但结果不对，你可以提醒它：“在 Windows 上用 Invoke-WebRequest 或者 curl.exe”。

这里有个小技巧：你可以提前在.claude/settings.json里配置好常用命令的别名或者替换规则，这样 Claude 在 Windows 上就会自动用正确的命令。比如：

{ "commandAliases": { "curl": "curl.exe", "ls": "Get-ChildItem" } }

5.3 代码修改与版本控制集成

Claude Code 改完代码之后，你可以让它帮你提交：

把刚才的改动提交一下，写个合适的 commit message。

它会先跑git status看有哪些文件变了，然后git add，再git commit。commit message 它会自动生成，通常是英文的，比如 “Add Express server with Hello World endpoint”。如果你想要中文的 commit message，可以提前告诉它：“commit message 用中文写”。

如果项目里有.gitignore没配好，Claude 可能会把node_modules也加进去。这时候你可以让它先检查.gitignore，或者手动改一下再让它提交。我一般会在项目初始化阶段就让 Claude 帮我生成一个标准的.gitignore，省得后面出问题。

6. 常见问题与排查技巧实录

6.1 安装与启动阶段的典型报错

问题一：npm install -g报错EACCES或EPERM

这个前面提过，主要是权限问题。解决方案是改 npm 全局目录到用户目录，或者用管理员身份运行终端。但我不建议长期用管理员终端，因为 Claude Code 执行命令时也会继承管理员权限，风险太大。

问题二：claude命令找不到

PATH 没配好。检查npm config get prefix的输出，把这个路径加到系统环境变量的 Path 里。改完之后一定要重开终端。

问题三：认证失败，提示 “organization has disabled claude subscription access”

这是组织策略限制，不是技术问题。你需要用个人账号的 API Key，或者联系管理员开通权限。

6.2 运行时的权限与编码问题

问题四：PowerShell 执行策略阻止脚本

前面给了Set-ExecutionPolicy的解法。如果公司电脑不让改执行策略，你可以让 Claude 用powershell -ExecutionPolicy Bypass -File script.ps1的方式来跑脚本，这样只对单次执行绕过策略，不影响全局。

问题五：中文乱码

Windows 终端默认编码可能是 GBK，而 Claude Code 输出的是 UTF-8。解决办法是在 Windows Terminal 的配置文件里，把 PowerShell 的启动参数加上-NoExit -Command "chcp 65001"，这样每次开终端自动切到 UTF-8。或者在 Claude Code 的配置里指定输出编码。

问题六：Claude 执行的命令在 Windows 上不存在

比如它用了grep、sed、awk这些 Linux 命令。你可以装 Git Bash 或者 WSL，然后把 Claude Code 的默认 Shell 设成 bash。或者更简单的方式：在项目配置里告诉 Claude “当前环境是 Windows，请使用 PowerShell 兼容的命令”。

6.3 性能与资源占用优化

Claude Code 本身是个 Node 进程，内存占用不算大，但如果你同时开着 VS Code、Docker、多个浏览器标签，机器可能会卡。我一般会把 Claude Code 跑在 Windows Terminal 的一个独立标签里，不用的时候直接关掉，需要的时候再开。它不像某些后台服务需要常驻，按需启动就行。

另外，如果你觉得响应速度慢，可以检查一下是不是走了代理或者网络延迟高。在配置里把maxTokens调小一点也能加快响应，因为生成的内容少了。

7. 进阶玩法：本地模型与多环境协同

7.1 调用本地模型（如 LM Studio）

Claude Code 默认走 Anthropic 的云端 API，但如果你有本地模型，比如用 LM Studio 跑的开源模型，也可以接进来。LM Studio 提供了一个兼容 OpenAI 格式的本地 API 端点，你可以在 Claude Code 的配置里把 API Base URL 指向http://localhost:1234/v1，然后指定模型名称。

这样做的优点是数据不出本地，适合处理敏感代码。缺点是本地模型的能力通常不如云端模型，复杂任务可能搞不定。我的建议是：日常简单补全和解释用本地模型，复杂重构和架构设计还是走云端。

7.2 在 WSL2 中运行 Claude Code

如果你已经装了 WSL2，其实可以在 WSL 里跑 Claude Code，体验会更接近 Linux 原生环境。安装步骤和在 Ubuntu 上一样：

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs npm install -g @anthropic-ai/claude-code

然后在 WSL 里配好 API Key 就能用。好处是终端命令兼容性更好，坏处是文件系统跨 Windows 和 Linux 的时候路径映射有点绕。我一般是在 WSL 里跑 Claude Code，但项目文件放在 Windows 盘上，通过/mnt/c/...访问。这样 VS Code 也能用 Remote-WSL 扩展直接编辑，两边不耽误。

7.3 多项目配置隔离与团队协作

如果你同时维护多个项目，每个项目的 Claude Code 配置可能不一样。比如 A 项目用 Jest 测试，B 项目用 Vitest。这时候可以在每个项目的.claude/settings.json里分别配置testCommand，Claude 就会根据当前项目自动选用正确的命令。

团队协作方面，你可以把.claude/settings.json提交到 Git 仓库里，这样团队成员的 Claude Code 行为一致。但注意不要把包含 API Key 的config.json提交上去，那个文件应该在.gitignore里。

8. 我踩过的坑与最后几条实用建议

第一个坑是终端编码。我一开始在 CMD 里跑 Claude Code，中文输出全是乱码，后来换到 Windows Terminal 加 UTF-8 才解决。如果你也在用 CMD，赶紧换。

第二个坑是命令确认。我有一次图省事，把autoApprove设成了 true，结果 Claude 在帮我清理日志的时候，把整个logs目录删了，包括我还没分析完的调试日志。从那以后，我再也不开全局自动确认了。

第三个坑是Node 版本。我有一台老机器上装的是 Node 16，Claude Code 装是装上了，但跑起来各种报错。后来升到 Node 20 LTS 就一切正常。所以别偷懒，版本该升就升。

最后分享一个小技巧：如果你经常需要让 Claude 帮你跑同一类命令，比如每次都要先cd到某个目录再执行，可以在.claude/settings.json里配一个preCommands数组，Claude 会在执行你的指令前自动跑这些前置命令。这个功能文档里没怎么提，但实测很好用。