1. 为什么要在 Windows 上认真折腾 Claude Code如果你平时主力开发环境是 Windows又恰好对命令行 AI 编程助手感兴趣那 Claude Code 这个名字大概率已经在你视野里晃过好几轮了。它本质上是一个跑在终端里的 AI 编程代理能直接读写你本地的项目文件、执行命令、跑测试、改代码交互方式跟传统的 IDE 插件完全不是一回事。很多人第一次听说它是在 Mac 或者 Linux 的教程里于是产生了一个错觉这东西在 Windows 上是不是不好使实测下来能跑而且跑得挺稳只是安装路径、终端选择、环境变量这几块比 Unix 系多几个坑踩过一次基本就顺了。这篇内容面向的是想在 Windows 上把 Claude Code 真正用起来的人不管你是刚接触命令行工具的新手还是已经用过一段时间的开发者都能从中找到可以直接抄作业的步骤和避坑经验。我会从安装前的环境准备讲起把 Node.js、Git、终端选择这些前置条件一个个拆开说清楚然后进入 Claude Code 的安装、配置、VSCode 集成最后重点讲我在实际使用中遇到的那些坑——比如权限报错、路径空格问题、终端编码乱码、升级失败等等。整篇内容基于 Windows 11 环境实测Windows 10 22H2 及以上版本同样适用。需要提前说明的是Claude Code 的安装方式在不同版本之间有过调整网上有些教程已经过时了。我会以当前主流可用的方式为准同时把原理讲透这样即使后续官方改了安装命令你也能自己判断该怎么调整。另外本文不涉及任何网络代理相关的内容所有操作都假设你在正常的网络环境下进行如果遇到网络层面的问题请自行查阅官方文档或相关社区讨论。2. 安装前的环境准备别急着敲命令2.1 Node.js 版本选择与安装细节Claude Code 是通过 npm 分发的所以 Node.js 是第一个必须搞定的东西。这里有个很多人会忽略的点Node.js 的版本不能太低。根据我的实测Node.js 18 LTS 及以上版本才能稳定运行推荐直接用 20 LTS 或者 22 LTS。如果你电脑上已经装了 Node.js先打开终端敲一下node -v看看版本号低于 18 的话建议升级别想着凑合用后面大概率会报一些莫名其妙的错。安装 Node.js 最省心的方式是去官网下载 LTS 版本的 Windows Installer.msi 文件双击一路下一步就行。安装过程中有一个选项叫 Add to PATH默认是勾选的千万别取消。这个选项会把 Node.js 和 npm 的可执行文件路径写进系统环境变量取消的话你就得手动配置徒增麻烦。安装完成后关掉所有已经打开的终端窗口重新开一个再敲node -v和npm -v两个都能正常输出版本号才算成功。如果你之前装过 Node.js 但是版本混乱建议先用控制面板卸载干净再重新安装。我遇到过有人电脑里同时存在 nvm-windows 和官方安装包两个来源的 Node.js导致node命令指向的版本和npm实际使用的版本不一致排查了半天才发现是环境变量顺序问题。所以如果你用了 nvm-windows 来管理 Node.js 版本那就统一用 nvm 来切换不要再混用官方安装包。还有一个细节npm 的全局安装目录最好确认一下。默认情况下npm 全局包会装在C:\Users\你的用户名\AppData\Roaming\npm下面这个路径本身没问题但如果你的用户名包含中文或者空格某些工具可能会出问题。检查方法是敲npm config get prefix如果输出路径里有中文建议改到一个纯英文无空格的路径比如C:\npm-global然后把这个路径加到系统 PATH 里。具体操作是npm config set prefix C:\npm-global设置完之后记得把C:\npm-global添加到系统环境变量 PATH 中否则全局安装的命令行工具会找不到。2.2 Git 安装与配置要点Claude Code 在很多场景下需要调用 Git 来查看文件变更、生成 diff、提交代码等所以 Git 也是必备的。Windows 上安装 Git 同样推荐去官网下载安装包安装过程中有几个选项值得注意。第一个是 Adjusting your PATH environment建议选 Git from the command line and also from 3rd-party software这样 Git 命令在 CMD、PowerShell、Git Bash 里都能用。第二个是 Choosing the default editor used by Git如果你不习惯 Vim可以改成 Nano 或者你熟悉的编辑器不然每次 Git 让你输入提交信息的时候会一脸懵。第三个是 Configuring the line ending conversions这个对 Windows 用户特别重要。建议选 Checkout Windows-style, commit Unix-style line endings也就是默认的推荐选项。这样 Git 在检出文件时会把换行符转成 CRLF提交时再转回 LF避免因为换行符差异导致整个文件被标记为已修改。安装完 Git 之后打开终端配置一下用户名和邮箱这是提交代码的前提git config --global user.name 你的名字 git config --global user.email 你的邮箱另外建议把默认分支名改成 main跟主流平台保持一致git config --global init.defaultBranch main2.3 终端选择PowerShell、CMD 还是 Windows TerminalClaude Code 是一个终端应用你用什么终端跑它直接影响使用体验。Windows 上常见的选择有 CMD、PowerShell、Windows Terminal、Git Bash 这几种。我的建议是优先用 Windows Terminal它是微软近几年主推的终端宿主支持多标签、分屏、自定义主题而且能同时承载 PowerShell、CMD、Git Bash 等多种 shell体验比老式的 CMD 窗口好太多。如果你还没装 Windows Terminal可以直接在 Microsoft Store 里搜索安装或者在 GitHub 上下载安装包。装好之后把默认配置文件设成 PowerShell 7也就是 pwsh而不是 Windows 自带的 PowerShell 5.1。PowerShell 7 跨平台、性能更好、语法更一致对 Claude Code 的兼容性也更好。安装 PowerShell 7 同样可以通过 Microsoft Store 或者 GitHub 安装包完成。为什么不推荐 CMD因为 CMD 的编码支持太差默认是 GBK遇到 UTF-8 字符容易乱码而且不支持很多现代终端特性。Git Bash 虽然能用但它在 Windows 上的路径映射机制有时候会让 Claude Code 产生困惑比如/c/Users/xxx和C:\Users\xxx之间的转换。所以综合来看Windows Terminal PowerShell 7 是目前最稳的组合。2.4 确认系统环境变量与权限在安装 Claude Code 之前还有两个系统层面的检查要做。第一确认你的用户账户有管理员权限因为 npm 全局安装某些包的时候可能需要写入系统目录。第二确认系统的执行策略没有把 PowerShell 脚本完全锁死。Windows 默认的 PowerShell 执行策略是 Restricted不允许运行任何脚本这会导致 npm 的某些脚本执行失败。你可以用管理员身份打开 PowerShell运行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这个命令的意思是允许运行本地脚本和来自可信来源的远程签名脚本安全性可以接受同时不会像 Unrestricted 那样完全不设防。设置完之后可以用Get-ExecutionPolicy确认一下。3. Claude Code 安装与首次配置3.1 安装命令与版本确认环境准备好之后安装 Claude Code 本身其实就一行命令npm install -g anthropic-ai/claude-code这里的-g表示全局安装装完之后你可以在任何目录下直接敲claude命令。安装过程可能需要一两分钟取决于网络速度和 npm 源。如果你在国内网络环境下觉得慢可以临时切换到国内镜像源比如npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com装完之后敲claude --version确认一下版本号。如果提示claude不是内部或外部命令说明 npm 全局路径没有正确加到 PATH 里回到 2.1 节检查npm config get prefix的输出路径是否在系统环境变量中。这里有个常见误区有些人用npx anthropic-ai/claude-code来运行这样确实能跑但每次都会去检查更新启动速度慢而且不利于后续配置。所以还是建议全局安装。3.2 首次启动与认证流程第一次运行claude命令时它会引导你完成认证。当前主流的方式是通过浏览器授权终端会输出一个链接你在浏览器里打开、登录、授权然后把拿到的验证码粘贴回终端。整个过程跟很多 CLI 工具的 OAuth 流程类似不算复杂。认证信息会保存在你的用户目录下具体路径是C:\Users\你的用户名\.claude或者类似的配置目录。这个目录里会存放认证凭证、配置文件、历史记录等。如果你后续需要切换账号或者重置配置可以把这个目录备份后删除重新走一遍认证流程。需要注意的是认证凭证是有有效期的过期之后需要重新授权。如果你发现 Claude Code 突然提示未授权先检查一下是不是凭证过期了重新走一遍认证即可不用重装。3.3 配置文件详解与常用参数Claude Code 的配置可以通过配置文件或者环境变量来管理。配置文件通常位于用户目录下的.claude文件夹里文件名可能是settings.json或者config.json具体取决于版本。你可以通过claude config命令来查看和修改配置也可以直接编辑文件。几个比较实用的配置项包括默认模型选择、是否自动确认文件修改、终端输出详细程度等。比如你可以设置默认使用哪个模型避免每次都要手动指定。也可以通过环境变量来覆盖配置比如设置ANTHROPIC_API_KEY来使用 API 密钥认证而不是 OAuth。在实际使用中我建议把常用的配置项写进配置文件而不是每次敲命令行参数。这样你在不同项目目录下切换时行为是一致的。另外如果你有多个项目需要不同的配置可以在项目根目录下放一个.claude文件夹里面放项目级别的配置Claude Code 会优先读取项目级配置。3.4 在 VSCode 中集成 Claude Code虽然 Claude Code 是终端工具但很多人日常写代码还是在 VSCode 里所以把它和 VSCode 结合起来用会舒服很多。最简单的做法是在 VSCode 里打开集成终端直接运行claude。VSCode 的集成终端默认就是 PowerShell 或者你配置的 shellClaude Code 在里面跑没有任何问题。更进一步的做法是利用 VSCode 的任务Task功能把 Claude Code 配置成一个可一键启动的任务。在项目根目录下创建.vscode/tasks.json内容大概是这样{ version: 2.0.0, tasks: [ { label: Claude Code, type: shell, command: claude, problemMatcher: [], presentation: { reveal: always, panel: dedicated } } ] }这样你就可以通过CtrlShiftP打开命令面板运行 Tasks: Run Task选择 Claude Code 来启动。它会在一个专用面板里打开不会干扰你其他的终端会话。另外如果你在 VSCode 里装了 Claude Code 相关的扩展如果有的话也可以直接在编辑器里调用。不过截至我写这篇内容的时候官方主要还是以终端交互为主VSCode 扩展生态还在发展中所以终端方式仍然是最可靠的。4. 实操过程中的核心环节与避坑指南4.1 路径空格与中文目录引发的血案这是 Windows 用户最容易踩的坑没有之一。Claude Code 在内部会调用很多命令行工具而这些工具对路径中的空格和中文处理能力参差不齐。如果你的项目放在C:\Users\张三\My Projects\my-app这样的路径下空格和中文同时出现大概率会遇到各种奇怪的报错比如文件找不到、命令执行失败、diff 生成异常等等。我的建议是所有开发项目统一放在一个纯英文、无空格的路径下比如C:\dev\projects\my-app。用户目录如果包含中文也没关系只要项目路径本身是干净的就行。如果你已经有很多项目散落在带中文的路径下可以考虑在C:\dev下建一个目录用符号链接或者直接移动过去。检查方法很简单在终端里cd到你的项目目录敲pwd或者echo %cd%看看输出的路径里有没有空格和中文。有的话趁早换路径别等到出问题了再折腾。4.2 终端编码乱码的根治方法Windows 终端默认编码是 GBK而 Claude Code 输出的内容大量使用 UTF-8这就导致中文显示乱码、特殊符号变成问号等问题。解决办法分两步。第一步把终端的代码页改成 UTF-8。在 PowerShell 里运行chcp 65001这个命令会把当前会话的代码页设为 UTF-8。但它是临时的关掉终端就失效了。要永久生效可以在 PowerShell 的配置文件$PROFILE里加上这一行。用notepad $PROFILE打开配置文件如果没有就创建一个然后加上[Console]::OutputEncoding [System.Text.Encoding]::UTF8 $OutputEncoding [System.Text.Encoding]::UTF8第二步确保系统区域设置里的 Beta: Use Unicode UTF-8 for worldwide language support 选项被勾选。这个选项在 控制面板 - 区域 - 管理 - 更改系统区域设置 里。勾选之后重启电脑系统的默认编码就会变成 UTF-8很多乱码问题会从根本上消失。不过要注意这个选项可能会影响一些老旧的、只支持 GBK 的软件如果你有这类软件可能需要权衡一下。4.3 权限报错与管理员模式的取舍在 Windows 上跑命令行工具权限问题几乎不可避免。常见的报错包括 EACCES: permission denied、EPERM: operation not permitted 等。这些通常发生在 npm 全局安装、写入系统目录、或者 Claude Code 尝试修改某些受保护文件的时候。一个常见的误区是直接用管理员身份运行终端。这样做确实能绕过权限检查但会带来两个问题一是所有由 Claude Code 创建的文件都会带上管理员权限后续用普通用户身份操作时可能无法修改二是某些工具在管理员模式下行为会发生变化比如 Git 的凭证管理。更稳妥的做法是只在确实需要管理员权限的操作中使用管理员终端比如全局安装 npm 包。日常使用 Claude Code 时用普通用户终端即可。如果遇到权限报错先看看是哪个文件或目录没有权限针对性地修改该目录的权限而不是无脑提权。具体操作是右键点击报错涉及的目录选择 属性 - 安全 - 编辑给你的用户账户加上 完全控制 权限。如果是系统目录谨慎操作最好先查清楚这个目录是干什么的。4.4 升级失败与版本回退的处理Claude Code 更新比较频繁升级命令就是重新跑一遍安装命令npm install -g anthropic-ai/claude-code但有时候升级会失败报错可能是网络问题、npm 缓存问题、或者旧版本文件被占用。遇到这种情况可以按以下顺序排查先清理 npm 缓存npm cache clean --force然后检查是否有正在运行的 Claude Code 进程占用了文件有的话先关掉。如果还是不行可以先卸载再安装npm uninstall -g anthropic-ai/claude-code npm install -g anthropic-ai/claude-code如果新版本有问题想回退到旧版本可以指定版本号安装npm install -g anthropic-ai/claude-code1.0.0具体版本号可以去 npm 包页面查看历史版本列表。回退之后建议把自动更新关掉避免它又给你升回去。4.5 常见问题速查表问题现象可能原因解决方法claude不是内部或外部命令npm 全局路径未加入 PATH检查npm config get prefix将输出路径加入系统 PATH启动时报错 EACCES权限不足用管理员终端重新安装或修改目录权限中文显示乱码终端编码非 UTF-8执行chcp 65001并设置 PowerShell 配置文件文件读写失败路径含空格或中文将项目移到纯英文无空格路径认证失败凭证过期或网络问题删除.claude目录重新认证升级后无法启动旧文件残留或缓存问题清理 npm 缓存卸载后重装Git 操作报错Git 未安装或未配置安装 Git 并配置 user.name 和 user.email终端输出卡顿终端性能问题换用 Windows Terminal关闭不必要的渲染效果5. 把 Claude Code 用顺手的几个进阶技巧5.1 项目级配置与多项目隔离当你同时在多个项目里使用 Claude Code 时项目级配置就显得很重要了。在项目根目录下创建一个.claude文件夹里面放一个settings.json可以定义这个项目专属的行为比如忽略哪些文件、使用哪个模型、是否自动执行命令等。这样你在不同项目之间切换时Claude Code 会自动读取对应的配置不需要手动调整。另外建议把.claude文件夹加入.gitignore避免把个人配置提交到仓库里。如果团队里有人也用 Claude Code可以约定一个共享的配置模板放在仓库里但个人覆盖配置不提交。5.2 与 Git 工作流的配合Claude Code 和 Git 的配合非常紧密它能帮你生成提交信息、查看 diff、甚至自动提交。但这里有个经验不要让 Claude Code 自动执行git push或者git reset --hard这类危险操作。你可以在配置里限制它只能执行只读的 Git 命令写操作由你手动确认。具体做法是在配置里设置命令白名单只允许git status、git diff、git log等只读命令自动执行git commit、git push等需要你确认。这样既能享受便利又不会因为 AI 误操作导致代码丢失。5.3 性能优化与资源占用控制Claude Code 在运行时会占用一定的内存和 CPU尤其是在处理大项目或者执行复杂任务时。如果你觉得电脑变卡可以试试这几个优化手段。第一限制它扫描的文件范围。在项目配置里排除node_modules、dist、.git等不需要它关注的目录减少文件扫描量。第二避免在超大仓库的根目录直接启动可以先cd到具体的子模块目录。第三如果只是做简单的代码问答不需要它读写文件可以用更轻量的交互模式。5.4 安全使用习惯与数据保护最后聊聊安全。Claude Code 能读写你的本地文件所以使用习惯很重要。第一不要在包含敏感信息如密钥、密码、个人隐私数据的目录下随意让它扫描。第二定期检查它生成的提交和文件修改确认没有意外改动。第三如果项目涉及商业机密了解清楚数据是如何传输和存储的必要时使用本地模型或者限制其网络访问。我在实际使用中的体会是把 Claude Code 当成一个能力很强但需要监督的助手而不是完全放手的自动化工具。它能极大提升效率但最终的代码质量和安全责任还是在你身上。踩过几次坑之后我现在会习惯性地在让它执行写操作之前先看一眼它打算做什么确认无误再放行。这个习惯花不了几秒钟但能避免很多麻烦。