Windows 下 Claude Code 从安装到实战：终端 AI 编程避坑指南

从 npm 全局安装到终端里敲下claude那一下，Windows 用户跑通 Claude Code 通常要比 mac 用户多绕三四个弯。我自己在 Windows 11 上已经把它跑进日常开发流里大半年，从早期的路径报错、权限拦截、乱码输出，到现在稳定处理重构、写测试、审代码，中间踩过的坑确实值得整理成一份能直接照做的指南。这篇文章不是官方文档的翻译，而是基于真实项目里的实操经验，把 Windows 下的安装配置、日常用法、模型切换和专属避坑点一次性说清楚。适合想在 Windows 上把 Claude Code 真正用起来的开发者，不管之前用的是 Cursor 还是纯手写代码，照着一路做下来基本能落地。

1. 落地前的认知准备：Claude Code 在 Windows 上的运行逻辑

1.1 Claude Code 到底是个什么形态的工具

Claude Code 是 Anthropic 官方推出的命令行 AI 编程代理，不是那种在聊天框里一问一答的插件，而是真正长在终端里的 Agent。给它一个目标，它能自己读项目文件、搜索代码、定位问题、修改多个文件、执行测试命令，然后基于运行结果继续调整，直到任务完成。

这种形态决定了它和 IDE 插件的本质区别：它拥有文件系统和命令行的访问能力。在 mac 和 Linux 上这很自然，因为这两个系统天生就是开发者环境。但 Windows 不一样，进程管理方式、路径格式、终端编码、权限模型都有自己的一套逻辑，这就导致同样一条命令，在 mac 上顺利跑完，在 Windows 上可能卡在某个莫名其妙的 shell 细节上。

所以先说清楚：Claude Code 在 Windows 上完全可用，但不是开箱即用，需要做好三件事——选对终端、装对 Node 环境、理解它的权限交互方式。这三件事做完，后面就顺了。

1.2 终端和 Shell 选择：这一步决定一半的体验

我在 Windows 上测试过 CMD、PowerShell 5.1、PowerShell 7、Git Bash 四类环境，结论非常明确：优先用 Windows Terminal 加 PowerShell 7，其次 Git Bash，最后才是 CMD。

原因有几个。第一，Claude Code 的交互界面大量依赖 ANSI 转义序列来做光标移动、颜色渲染和动态刷新，CMD 对这套支持得最差，跑起来经常出现残留文本和错位。第二，PowerShell 5.1 默认编码是 GBK，和 Claude Code 输出的 UTF-8 文本不一致，中文内容会直接乱码，而 PowerShell 7 默认就是 UTF-8，省掉很多麻烦。第三，Claude Code 会通过 Bash 工具调用系统命令来执行任务，PowerShell 7 的命令兼容性和错误信息可读性比 CMD 好太多。

PowerShell 7 安装很简单，用 winget 一条命令就行：

winget install Microsoft.PowerShell

装完在 Windows Terminal 的设置里把默认配置文件改成 PowerShell 7，后面所有操作都在这个环境里做。这一步值得先做，因为后面所有坑的排查效率都取决于终端是否顺手。

1.3 Node.js 版本：别用太旧，也别盲目追新

Claude Code 是 npm 包，运行在 Node.js 上，所以 Node 环境是硬前提。官方要求 Node 18 以上，但我实测下来建议用 20 LTS 或 22 LTS，不要用 18 的早期小版本，也不要直接用刚发布的最新奇数版本，稳定优先。

Windows 上装 Node 我强烈建议走 nvm-windows，而不是直接下载安装包。原因很实际：AI 工具链更新速度快，Claude Code 本身迭代也快，加上你未来还可能装其他 npm 全局工具，每个工具对 Node 版本要求不一样。用 nvm-windows 可以随时切换版本，避免卸载重装的痛苦。

nvm install 20 nvm use 20 node -v npm -v

有个细节容易忽略：如果电脑上已经装了 Node 安装包版本，需要先卸载干净再装 nvm-windows，否则两个版本管理器会互相干扰，PATH 里出现诡异的老版本路径。

2. 从零安装：全局安装、登录认证与首个任务

2.1 npm 全局安装 Claude Code 的完整步骤

确认 Node 环境没问题后，安装过程其实就是一条命令：

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

装完验证版本：

claude --version

如果提示claude 不是内部或外部命令，大概率是 npm 全局目录没有加进 PATH。Windows 下 npm 全局目录默认在%APPDATA%\npm，也就是C:\Users\你的用户名\AppData\Roaming\npm。打开系统环境变量设置，把这个路径加进 Path，重启终端再试。

我自己在安装时遇到过另一个坑：公司电脑的实时杀毒软件会把 npm 全局目录下的临时文件拦截掉，导致安装到一半报EPERM: operation not permitted。排查方法是看安装日志里卡在哪个文件上，如果是 node.exe 或相关脚本被拦截，需要在杀毒软件里把目录加白名单。这个坑很隐蔽，因为报错信息看起来像是权限问题，实际是安全软件在捣乱。

2.2 登录认证：浏览器授权与 API Key 两种方式

安装完先别急着用，要登录。首次运行claude会进入初始化流程，弹出浏览器授权窗口。这里有两个实测经验：

第一，如果浏览器没有自动弹出来，不用慌。终端里会显示一个完整的授权 URL，手动复制到浏览器打开就行，别傻等自动跳转。第二，如果浏览器里登录后终端迟迟没反应，大概率是防火墙或企业网络策略拦了本地回环监听端口，这时候最稳妥的方案是改用 API Key 认证。

API Key 的方式很直接，设置环境变量即可：

$env:ANTHROPIC_API_KEY="你的key"

设置好后再启动claude，它会直接跳过浏览器授权环节。这个方式也方便脚本化和 CI 环境使用。要注意的是 API Key 和账号订阅计费是两套系统，用 API Key 跑的任务按 token 计费，如果用订阅包，走浏览器授权更划算。团队里多人共用时，建议每个人用自己的授权或独立的 Key，别在公共终端里粘贴共享密钥。

2.3 跑通第一个任务：进入项目目录再启动

登录成功后的第一个动作，决定了你对这个工具的印象。正确姿势是：先cd进项目目录，再运行claude，这样它自动把当前目录作为工作区。如果项目在别的目录下，也可以用/add-dir命令把一个新目录加入工作区。

第一次交互建议从简单任务开始，比如让它读一下项目结构，梳理 README 没写清楚的模块关系。不要一上来就丢一个跨模块重构的大需求，Windows 下第一次跑工具调用时你会看到一堆权限确认框，大任务会让这个确认过程变得很长，体验容易崩。

3. 核心玩法拆解：交互模式、非交互模式与命令执行权限

3.1 交互式开发：把 Claude Code 当结对同事用

日常开发里我 90% 的时间用的是交互模式。启动claude后直接描述需求，比如“找到登录接口超时的根因并修复”，它会先拆解任务、列出计划，然后逐步读代码、定位问题、修改文件、运行验证。

这里要说清楚它的工作方式：Claude Code 不是一个只会生成的 Composer，它有工具调用能力，每一步操作都会请求权限。默认模式下，读文件通常直接放行，写文件会请求确认，执行命令也会请求确认。这种设计在前期会觉得繁琐，但必须理解它的价值——AI 执行权限越大，出错时波及范围越大。我见过不少人上来就开--dangerously-skip-permissions，结果 Claude 把测试数据库里的数据清了才反应过来，这种模式只应该在隔离的沙箱或 CI 环境里用。

交互模式里几个高频命令先记下来：

• /add-dir：把其他目录加入工作区
• /model：切换模型
• /compact：压缩对话历史，重新组织上下文
• /clear：清空当前会话
• /permissions：查看和调整权限设置

3.2 非交互模式：把 Claude Code 接进自动化和脚本

除了交互模式，Claude Code 支持纯命令行调用，这是 Windows 场景下被低估的能力。一条命令直接出结果，非常适合写进批处理脚本、Git 钩子、CI 流水线或者 VS Code 任务里。

claude -p "分析当前目录的代码，找出未处理的异常并列出文件位置"

想要结构化输出，加--output-format json：

$result = claude -p --output-format json "统计这个项目的 TODO 数量" | ConvertFrom-Json $result.result

这个能力在 Windows 上尤其好用，因为很多开发者习惯写 PowerShell 脚本处理重复劳动，现在可以把“理解代码”这类偏智能的工作也并进来。比如我写过一个小脚本，每天下班前自动让 Claude Code 扫描当天改动的文件并生成变更摘要，配合 git log 的数据，输出成 Markdown 报告。整个过程不需要打开交互终端。

3.3 Claude Code 如何直接执行终端命令

热搜里有一条“claude code 如何直接执行终端命令”，这个能力本质上是它的 Bash 工具。Claude Code 在 Windows 下执行命令时调用的是 PowerShell，所以它能跑绝大部分 PowerShell 命令。

但这里有两个 Windows 特有的注意点。第一是执行策略，有些机器的 PowerShell 默认执行策略受限，会导致部分脚本命令被拦，可以在启动 Claude Code 前先放开当前进程的策略：

Set-ExecutionPolicy -Scope Process Bypass

第二是命令是否需要提升权限。Claude Code 本身以当前用户的权限运行，如果任务里需要管理员权限的操作，比如改系统服务、写 Program Files 目录，它会直接失败。这种情况不要指望 Claude Code 自己去 UAC 提权，正确做法是给任务拆开，把需要管理员权限的部分用你自己的提权终端做。

权限模式也在这里发挥作用。--permission-mode acceptEdits表示自动接受文件修改，适合你已经在盯着输出、确认它改得对的场景。--permission-mode plan是只读规划模式，它只分析、给方案、不落盘，非常适合评审阶段。合理组合这几个模式，比全程确认或全程免确认都更高效。

4. 让 Claude Code 更懂项目：CLAUDE.md 记忆与 MCP 扩展配置

4.1 CLAUDE.md：写清楚项目背景，AI 才不会瞎猜

用过几次之后你会发现，Claude Code 对项目的理解深度，很大程度上取决于你给了它多少上下文。它每次启动会读取项目根目录下的CLAUDE.md文件，以及用户目录~/.claude/CLAUDE.md下的全局记忆。这是它理解项目的核心机制，比在对话里反复解释高效得多。

项目级CLAUDE.md我建议至少包含四类内容：项目简介与技术栈、常用构建和测试命令、代码风格约定、禁止事项。举个例子：

# 订单系统 ## 技术栈 - 后端：Node.js + Express + PostgreSQL - 前端：React + TypeScript ## 常用命令 - 启动开发环境：npm run dev - 运行测试：npm test - 数据库迁移：npm run migrate ## 约定 - 所有数据库访问必须走 repository 层，禁止在路由里直接写 SQL - 错误处理统一用 AppError 包装 - 命名：接口文件用 xxx.service.ts，路由文件用 xxx.routes.ts ## 禁止 - 不要修改 src/config 下的配置文件 - 不要删除迁移历史文件

写完之后再跑 Claude Code，你会发现它的回答水平提升一个档次，因为它不需要在上下文中临时猜这些规则了。这个文件建议纳入版本管理，和.gitignore一样属于团队资产。

4.2 MCP 扩展：Windows 下 npx 这个坑必须绕过去

MCP（Model Context Protocol）是 Claude Code 扩展能力的方式，通过.mcp.json文件配置外部服务，比如数据库工具、浏览器自动化、知识库检索等。配置结构大概是：

{ "mcpServers": { "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory"] } } }

这段配置在 mac 上没问题，但到了 Windows 上大概率启动失败。原因是 Windows 没有npx这个可执行文件，只有npx.cmd，Claude Code 在解析命令时会找不到目标。这是我踩过最典型的 Windows 专属坑。

解决方案是显式指定cmd来执行：

{ "mcpServers": { "memory": { "command": "cmd", "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"] } } }

改完之后重启 Claude Code，用/mcp命令检查连接状态。如果还不行，再排查一下 npx 是否真的在 PATH 里，以及本机是否已经装了对应的 npm 包。MCP server 本质上是一个本地子进程，它出问题的排查思路和本地 Node 服务一模一样，日志不行就换版本，版本不行就查网络。

4.3 Windows 下与容器环境的联动注意点

如果你的 MCP server 或测试环境依赖 Docker Desktop，那么有一个和 Claude Code 无关但会被它牵连的坑：Docker Desktop 的 daemon 不能从提升权限的管理员终端启动，必须是普通终端启动。这个报错信息看起来很奇怪，实际原因是 Docker Desktop 为了避免依赖冲突强制校验终端权限，和项目代码没关系。遇到这种情况，关掉 Docker Desktop，从普通用户的 PowerShell 里重新启动它就行。这个坑在 Windows 上特别容易遇到，因为开发者习惯用管理员终端干所有事。

5. 与 VS Code 协同：把 Claude Code 嵌进编辑器工作流

5.1 VS Code 扩展安装与终端面板复用

Claude Code 有官方 VS Code 扩展，装完之后可以在编辑器内直接打开 Claude Code 面板，不用来回切窗口。扩展的好处不只是方便，更重要的是编辑器上下文可以传给 Claude Code，代码高亮、错误标记、当前选中的代码块都能被它感知，做局部修改时准确率明显提高。

安装方式很简单，在 VS Code 扩展市场搜索 Claude Code，安装 Anthropic 官方的那个即可。装好后侧边栏会出现入口，点击后会启动一个类似终端的会话面板。我实际用下来的感受是：如果任务涉及单个文件的局部优化，直接在扩展面板里跑，上下文衔接最顺；如果任务涉及全项目重构或者要跑多个测试命令，我反而切回独立 Windows Terminal，因为输出面板更宽松，长日志不会被编辑器折叠。

5.2 把 Claude Code 注册成 VS Code 自定义任务

另外一个套路是把 Claude Code 的非交互模式注册成 VS Code Task，这样按快捷键就能触发固定类型的 AI 操作，比如“审查当前改动”“生成提交信息”“补全测试”。这个做法把 AI 能力变成了编辑器里的一等公民，用起来非常顺手。

tasks.json示例：

{ "version": "2.0.0", "tasks": [ { "label": "claude: 审查当前改动", "type": "shell", "command": "claude", "args": ["-p", "--permission-mode", "plan", "审查当前工作区未提交的改动，输出问题清单和改进建议"], "presentation": { "panel": "dedicated", "reveal": "always" } } ] }

然后在keybindings.json里绑定快捷键：

{ "key": "ctrl+alt+shift+c", "command": "workbench.action.tasks.runTask", "args": "claude: 审查当前改动" }

配好之后，每天提交代码前按一下快捷键，Claude Code 会快速扫一遍 diff 并给出审查意见。多花两分钟做这个配置，换来的是一年下来无数次提交前的快速自查，很值。

6. 模型切换与兼容网关接入：解锁更多模型选择

6.1 官方模型：会话内切换最方便

Claude Code 默认用的模型是当前账号对应的默认模型，但在会话里可以用/model命令切换型号。三种主流模型的定位差异明显：轻量型号响应快、成本低，适合代码解读、测试生成这类任务；均衡型号是日常主力，代码生成质量和速度平衡；最强型号适合复杂架构设计、多文件重构、疑难 bug 定位，但响应速度慢、成本也最高。

我的习惯是：对话任务如果只是让 AI 查资料、改文案，直接切轻量型号；一旦任务涉及跨文件重构或者重构某个核心模块，立刻切到最强型号。会话中途切换是允许的，不要担心切来切去会丢失上下文。用环境变量ANTHROPIC_MODEL也可以固定某个型号，适合脚本化场景，但日常交互里用/model更灵活。

6.2 通过 Anthropic 兼容接口接入第三方模型

Claude Code 支持通过环境变量指定 API 地址，这项能力让它不只局限于官方模型。很多团队用兼容网关来统一管理模型入口、做审计日志、控制成本。配置方式很简洁：

$env:ANTHROPIC_BASE_URL="http://你的网关地址" $env:ANTHROPIC_API_KEY="你的密钥"

配置完成后再启动claude，请求就会发往网关，由网关转发给后端模型。以 DeepSeek 这类生态模型为例，只要网关侧实现了 Anthropic 兼容的请求格式，Claude Code 就能跑起来。这个做法的应用场景很明确：企业内部统一网关、模型对比测试、成本敏感项目降本。用之前有一件事必须确认——网关是否完整支持工具调用和流式输出。如果网关只做了文本对话的接口适配，Claude Code 连文件读取和命令执行都会瘫痪，看上去是能聊天的，但干不了活。

我给自己搭过一套本地测试环境，网关转发到不同模型，用同一组任务做横向对比。同一个重构需求，不同模型给出的方案风格差异非常大，有的激进、有的保守，这个对比用 Claude Code 的非交互模式批量跑非常方便。前提是你的网关稳定，因为任务跑一半网关超时，整个会话就断了，上下文得重新来。

7. Windows 专属坑与排查实录

7.1 乱码与编码问题：从源头解决

中文乱码是 Windows 用户遇到频率最高的问题，本质是字符编码不匹配。Claude Code 输出的是 UTF-8，而 Windows PowerShell 5.1 默认终端代码页是 GBK。解决办法优先级从高到低：

• 换 PowerShell 7，默认 UTF-8，这是治本。
• 老项目暂时没法换的，执行chcp 65001切代码页。
• 设置环境变量PYTHONUTF8=1或启用在 Windows Terminal 设置里把默认配置文件的所有代码页设为 UTF-8。

注意一点：chcp 65001只对当前窗口有效，新开窗口又变回去。所以这个方案只适合临时排查，长期还是要换终端。

7.2 路径与权限问题：长路径、目录访问与杀毒软件

Windows 的路径限制是个历史悠久的大坑。Claude Code 处理项目文件时会递归遍历目录，如果项目路径很深，比如C:\Users\用户名\Desktop\某个很长的项目名\src\components\...，就可能触发 Windows 的 MAX_PATH 限制，报错信息往往是EPERM或路径找不到。

解决方法有两个层面。系统层面，把注册表里的长路径支持打开：

New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

项目层面，尽量把工作目录放在盘符根目录附近，比如D:\projects\order-system，别放在桌面很深的多级目录下。另外一定要配置.claudeignore文件，把node_modules、dist、.git这类目录排除掉，否则 Claude Code 初次索引大项目时会扫描大量无用文件，又慢又容易触发权限问题。

7.3 常见错误速查表

7.4 资源占用与长会话优化

Claude Code 跑大项目时，内存和终端输出带宽都会被拉起来。长会话里上下文越来越长，响应速度下降是必然的，有两个工具要熟练用：/compact压缩历史，/clear开新会话。这两个操作都会丢失部分精确上下文，所以要在任务告一段落时主动清理。

另外建议把一次任务控制在一个合理范围内，不要让一次对话跨三个以上的子任务。一旦发现 Claude Code 开始反复读同一个文件，或者问你之前答过的问题，说明上下文已经乱了，立刻/clear重来比硬撑更省时间。

最后一件事：先让权限约束成为肌肉记忆

我把这套组合（Windows Terminal + PowerShell 7 + VS Code 扩展 + Claude Code）用了几个月之后，最大体会是：真正决定工具上限的不是安装配置，而是权限使用的纪律。一开始我急于看到它自主干活的爽感，开了完全跳过权限的模式，结果一次误删让我后悔了很久。后来我给自己定了规则：任何涉及写文件或执行命令的任务，前几轮全部走默认确认模式；等确认它对项目的理解准确了，再临时切acceptEdits；只有只读类任务才用plan模式。这个习惯坚持下来，Claude Code 在 Windows 上不仅没给我添乱，反而成了效率最稳定的一个工具。

最后再分享一个小操作：在项目的.claudeignore里除了排除node_modules，还可以把docs/archive、test/fixtures这类不经常改的目录也加进去。这样 Claude Code 每次扫项目会更快，上下文也不会被无关文件占据。先用小项目验证这整套流程，跑顺了再上核心业务仓库，你会感受到 Windows 下这个 Agent 工作流的真正价值。