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 KeyAPI 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_PROXYhttp://你的代理地址:端口 set HTTPS_PROXYhttp://你的代理地址:端口在 PowerShell 里用$env:HTTP_PROXYhttp://...的写法。配完之后Claude Code 的 API 请求就会走代理。但要注意有些代理只支持 HTTP 不支持 HTTPS或者需要认证这些都要根据你的实际网络环境调整。还有一个常见问题是 SSL 证书验证失败。如果你公司的代理做了 SSL 拦截Claude Code 可能会报证书错误。这时候可以临时设置set NODE_TLS_REJECT_UNAUTHORIZED0但这是下策因为关掉证书验证会降低安全性。更好的做法是把公司的根证书导入到 Node 的信任列表里具体操作稍微复杂一点这里不展开。5. 实操流程从零跑通一个完整项目5.1 创建项目并初始化 Claude Code假设我们有一个空目录my-project想用 Claude Code 帮我们搭一个简单的 Node.js 项目。首先进入目录cd C:\Users\你的用户名\projects\my-project然后启动 Claude Codeclaude第一次在这个目录启动它会问你要不要初始化项目配置。选 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 StudioClaude 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里分别配置testCommandClaude 就会根据当前项目自动选用正确的命令。团队协作方面你可以把.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 16Claude Code 装是装上了但跑起来各种报错。后来升到 Node 20 LTS 就一切正常。所以别偷懒版本该升就升。最后分享一个小技巧如果你经常需要让 Claude 帮你跑同一类命令比如每次都要先cd到某个目录再执行可以在.claude/settings.json里配一个preCommands数组Claude 会在执行你的指令前自动跑这些前置命令。这个功能文档里没怎么提但实测很好用。