说个特别常见的场景你在 VS Code 里写代码写到一半突然要去查一段 API 文档、改一个正则、补一组单元测试来回切窗口切到怀疑人生。我就是这么被 Claude Code CLI 救回来的——它是 Anthropic 官方出的命令行 AI 编程助手直接在终端里跑 Claude能读项目文件、执行命令、顺手帮你把代码改了省掉了浏览器和编辑器之间来回横跳的麻烦。这篇文章只干一件事把 Claude Code CLI 在 Windows 上安装、配置、日常使用、踩坑排查的完整过程讲透。适合三类人看一是被同事安利了 Claude Code 但卡在安装第一步的 Windows 用户二是想在 VS Code 里接一个终端编程助手、却不知道从哪下手的开发者三是想找个靠谱命令行 AI 工具、把日常开发效率提一档的效率党。我写的每一步都基于自己在 Windows 11 上反复安装、卸载、排错的真实操作照着抄基本都能过。1. 装之前先搞明白Claude Code CLI 到底解决什么问题1.1 一个住在终端里的编程助手Claude Code 是 Anthropic 在 2025 年推出的官方 CLI 工具官方定位是“agentic coding tool”翻译成大白话就是你在终端里跑一个claude命令它就能像一个远程结对编程的同事一样帮你阅读理解整个项目的结构、定位 bug、修改代码、执行测试命令甚至能连续多轮协作直到把任务做完。和网页版 Claude 最大的区别在于它直接长在你的项目目录里。它能调用Read、Edit、Glob、Grep这些工具去实际读写你磁盘上的文件也能通过Bash工具执行终端命令。换句话说它不只是“聊天”而是真正动手干活的 agent。你在终端里让它“帮我看看这个报错为什么会出现”它会自己去读日志、查代码、跑命令最后给你结论这体验和网页版完全不是一个物种。和 Claude 桌面版Claude Desktop的区别也顺便说清楚桌面版是一个带 GUI 的聊天客户端适合日常问答、文档处理Claude Code 是纯命令行工具适合在开发环境里干工程活。两者不冲突但如果你是冲着编码效率来的要装的是 CLI不是桌面版。很多人搜“claude code 桌面版”搜到的是 Claude Desktop装完发现不是一回事这里先帮各位避个雷。1.2 为什么 Windows 安装要单独拎出来讲按理说一个 npm 全局包安装不就是一个命令的事吗但 Claude Code 在 Windows 上还真不是敲完命令就能顺利用起来的。我统计了一下自己从装到用的过程中遇到的坑PowerShell 执行策略拦路、Node.js 版本不对、npm 全局路径没进 PATH、终端中文乱码、开发者模式没开导致权限问题……每一个都能卡住一批人。更麻烦的是Claude Code 很多官方文档默认以 macOS/Linux 为主Windows 相关的细节散落在各个 issue 和论坛帖子里。有人用 npm 装有人用官方 PowerShell 脚本装装完登录方式还不一样新手上路很容易懵。这篇文章就把 Windows 这条线单独捋清楚把环境、安装、配置、排错串成一条完整流程。2. 环境准备三步走Node.js、终端和开发模式2.1 第一步装对 Node.js 版本Claude Code 本质是一个 Node.js 应用通过 npm 分发所以 Node.js 是必须的前置条件。这里直接给结论Node.js 18 及以上版本推荐装 LTS长期支持版目前就是 20.x 或 22.x。版本太老会直接报错或者装完启动不了版本太新比如某些非 LTS 的奇数版本有时会遇到兼容问题。检查有没有装过 Node.js打开终端执行node -v npm -v如果提示“不是内部或外部命令”说明没装或者没配环境变量。去官网下载 Windows Installer (.msi) 版本一路下一步装完即可安装包默认会自动帮你配好 PATH。装完之后重新开一个新的终端窗口再跑一次上面的命令确认版本号能正常输出。这里有个 Windows 特有的坑如果你旧电脑上已经装过很老的 Node比如 12.x、14.x建议直接卸干净再装新版因为 npm 全局包的缓存和旧版本混在一起容易出现各种奇怪的报错。卸载后在控制面板里确认没有残留再重新装。2.2 第二步选好终端并调整执行策略Windows 上的终端选择直接影响安装体验。官方推荐用 Windows TerminalWindows 11 系统自带Windows 10 可以到微软商店免费装。Windows Terminal 的字体渲染、UTF-8 支持、复制粘贴体验都比老式 conhost 好一截Claude Code 输出的内容带颜色和格式在老终端里很容易显示错乱。装完终端后有一个必须处理的问题PowerShell 的执行策略。我第一次在 PowerShell 里跑 Claude Code 的安装脚本时直接报错无法加载文件 ... 因为在此系统上禁止运行脚本。这是 Windows 默认安全策略导致的默认限制脚本执行。解决办法是给当前用户开放远程签名模式Set-ExecutionPolicy -Scope CurrentUser RemoteSigned这条命令的意思是本地创建的脚本可以运行从网络下载的脚本必须有可信签名。设置完按 Y 确认然后重新打开终端。这个设置只影响当前用户不会改动系统全局策略安全性上可以接受。顺便说一句如果你已经装了 Git for Windows里面的 Git Bash 也是一个不错的替代终端。Claude Code 在很多 Linux 风格的命令处理上Git Bash 反而比 PowerShell 更顺手。但 Windows Terminal PowerShell 是官方主推的组合新手建议先用这个。2.3 第三步开启 Windows 开发者模式建议这一步知道的人不多但很关键。Claude Code 在运行时会创建符号链接symlink来管理自身的一些文件Windows 默认不允许普通用户创建符号链接导致安装后某些功能不可用或者报权限错误。开启方法很简单Windows 11 打开“设置 → 系统 → 开发者选项 → 开发者模式”打开开关Windows 10 在“更新和安全 → 开发者选项”里。开启后系统会提示需要重启或者安装开发者模式相关组件按提示操作就行。开发者模式本质上是给本机开发工具放开了一部分文件系统操作权限Claude Code 这类 agent 工具非常依赖这类能力。不开启也能装能跑但我在开启之前遇到过文件写入被拒绝的间歇性报错开启之后就再没出现过。这是成本最低、收益最明确的准备工作。3. 安装与首次登录从命令到能用的完整流程3.1 两种安装方式怎么选Claude Code 官方提供了两种安装方式Windows 上都支持我两种都试过给你说下区别。方式一npm 全局安装npm install -g anthropic-ai/claude-code这是最主流、最稳妥的方式。装了 Node.js 就能用卸载更新都方便而且很多后续的插件、扩展工具都默认依赖 npm 全局路径。缺点是对 npm 源的速度有要求默认官方源在国内部分网络环境下比较慢可以先把 npm 源切换到国内镜像npm config get registry npm config set registry https://registry.npmmirror.com设置后重跑安装命令速度会明显提升。注意改 registry 是全局性的配置会影响你之后所有的 npm 操作如果你公司有私有源要慎重。方式二官方 PowerShell 安装脚本官方文档还提供了 Windows 原生安装脚本在 PowerShell 里执行irm https://claude.ai/install.ps1 | iexirm是Invoke-RestMethod的简写iex是Invoke-Expression作用就是下载官方安装脚本并直接执行。这个方式会安装独立的原生版本后续更新可以通过claude update命令完成不需要依赖 Node.js。适合不想装 Node.js 的用户。我的建议如果你本来就有 Node.js 环境用 npm 方式如果你电脑干净、不想为了一个 CLI 装整个 Node 运行时用官方脚本。两边安装的产物不完全一样npm 方式更新要走 npm原生方式更新走claude update别混着用。我自己日常用的是 npm 方式主要因为后续很多周边工具链和 npm 生态耦合更深。3.2 验证安装是否成功装完之后关掉当前终端重新开一个这步很关键新装的 PATH 和权限配置需要新终端才生效然后执行claude --version能输出版本号类似1.0.x就说明安装成功。如果提示“claude 不是内部或外部命令”或者 PowerShell 提示“claude : 无法加载文件 claude.ps1”说明 npm 全局目录不在 PATH 里这部分在第 5 节排错里详细讲。顺便建议装完第一时间跑一下官方自带的帮助命令claude --help把输出大致扫一遍能看到所有支持的参数比如-p非交互模式、--continue继续上次会话、--model指定模型等。养成看 help 的习惯比看一百篇教程都有用。3.3 登录授权与 API Key 配置安装只是第一步真正要能用还得完成身份授权。Claude Code 的计费和身份认证有两条路线路线一Claude 账号订阅登录Pro/Max 用户在终端执行claude login它会生成一个一次性验证码并自动打开浏览器登录你的 Claude 账号完成授权。Pro 或 Max 订阅用户可以直接把额度给 Claude Code 用这种方式个人开发者用得最多。登录成功后授权信息会存在本地不需要每次重复登录。路线二API Key 计费如果你是通过 Anthropic API 按量付费需要设置环境变量setx ANTHROPIC_API_KEY sk-ant-你的一串keysetx是 Windows 写永久环境变量的命令写完后要重新打开终端才生效。注意API 计费和订阅计费是两套体系价格和额度完全独立。我个人的建议是日常写代码用订阅方式就够了API Key 更适合跑自动化脚本或者团队内部集成。登录完成后在你的项目目录下直接输入claude就进入交互式对话界面。第一次在某个目录运行时它会提示是否允许读写该目录的文件选允许。这一步就是热词里搜的“claude code cli 如何给完全访问权限”——更精确的做法是在配置文件里管理权限白名单后面展开讲。3.4 配置文件在哪里Windows 上 Claude Code 的配置路径和 Linux/macOS 略有区别记住这几个位置路径作用%USERPROFILE%\.claude.json全局配置和会话历史索引%USERPROFILE%\.claude\settings.json用户级设置权限、模型、行为偏好%USERPROFILE%\.claude\CLAUDE.md全局记忆文件所有项目的公共上下文项目目录\CLAUDE.md项目记忆文件只对当前项目生效settings.json支持自定义权限规则比如你想让它免确认直接运行npm run命令可以这样配{ permissions: { allow: [ Read(.*), Edit(.*), Bash(npm run *) ] } }这里的.*是正则匹配Bash(npm run *)表示所有以npm run开头的命令都可以直接执行不再逐一弹确认框。这是比全局跳过权限更细粒度、更安全的管理方式。千万别二话不说加--dangerously-skip-permissions参数跑等于把整台电脑的钥匙都交出去了后悔都来不及。4. 接入 VS Code把 CLI 变成顺手的工作流4.1 官方插件与终端内嵌推荐哪个Claude Code 和 VS Code 的搭配是 Windows 开发者最常用的组合。目前有两条路第一条是在 VS Code 的扩展市场里直接搜 “Claude Code for VS Code” 安装官方扩展。装完后左侧边栏会出现 Claude 面板直接在编辑器里对话代码改动会以 diff 形式展示接受/拒绝都很直观。扩展底层还是调用本地安装的 CLI所以前面的安装步骤是前提。第二条是“终端内嵌”路线直接在 VS Code 的集成终端里跑claude。好处是界面最干净跟平时用命令行一样配合 VS Code 的终端分屏左边写代码右边跟着 Claude 干活交互纯粹。我个人的实际感受如果以聊天、审查代码、改 bug 为主装官方扩展更舒服如果习惯键盘流和终端工作流终端内嵌就够了。两条路不冲突可以同时留着按场景切换。对了VS Code 的 Claude Code 扩展偶尔有版本和你本地 CLI 版本不匹配的情况报错提示让你升级——直接按提示跑claude update或者npm update -g anthropic-ai/claude-code就行。4.2 日常最值得记住的命令和操作刚开始用 Claude Code 的人容易一头扎进交互界面全靠自然语言对话。但很多核心操作在交互界面外就能完成用好 CLI 参数效率会高很多# 非交互模式直接给一个 prompt适合问简单问题 claude -p 这个项目用了什么构建工具 # 继续上次的会话这个我几乎每天用 claude --continue # 列出历史会话选择恢复 claude --resume # 指定模型 claude --model claude-sonnet-4-20250514进入交互模式之后有几个内部命令高频使用/help看所有命令/clear清空当前上下文/model切换模型/exit退出。另外按Tab键可以在 plan计划和 build执行两种模式之间切换——plan 模式下它只出方案不动手build 模式才会真正改文件。复杂任务我强烈建议先切到 plan 模式让它给方案你确认了再切回 build。很多人在意的是中文支持。Claude Code 的输入输出对中文都很友好直接在交互界面用中文下指令完全没问题。但 Windows 终端如果出现中文乱码一般是编码问题参考第 5 节的解决方式。4.3 CLAUDE.md让 Claude 记住项目规则这是被很多人忽略、但实际价值性价比极高的功能。CLAUDE.md放在项目根目录Claude Code 每次启动会话都会自动读取它相当于给 AI 写了一个“项目说明书”。我自己的项目里一般会写这些内容项目简介和技术栈前端 Vue 3 TypeScript、后端 NestJS 之类代码风格约定比如缩进、命名规范、组件组织方式常用命令测试怎么跑、构建怎么跑禁止事项比如某些目录不要动、某些文件不要改写完之后你会明显感觉到 Claude 对项目的理解上了一个台阶不再需要你每次重复解释背景。配合%USERPROFILE%\.claude\CLAUDE.md里的全局规则比如“回答使用中文”“不要修改锁文件”体验会平滑很多。这算是我用下来最像“调教 AI”的功能。5. Windows 高频坑位记录与排查手册5.1 权限类报错执行策略、完全访问权限Windows 上第一个拦路虎就是 PowerShell 执行策略报错长这样claude : 无法加载文件 C:\Users\xxx\AppData\Roaming\npm\claude.ps1 因为在此系统上禁止运行脚本。原因和处理方法在第 2 节已经说了Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。这里补充一个细节如果设置完报错说没有权限修改策略可能需要以管理员身份打开 PowerShell 再执行一次。另外如果你是在公司电脑上跑组策略可能锁死了执行策略那就只能找 IT 或者改用 Git Bash。第二个权限问题就是前面提到的“完全访问权限”。首次在某个目录运行claude时会问你是否允许访问当前目录选 allow 就行。但如果你用脚本批量跑任务会被这些权限确认弹窗不停打断。这时候用settings.json里的permissions.allow白名单精确放行而不是粗暴加--dangerously-skip-permissions。记住权限给的越具体日常越顺畅风险越低。5.2 环境变量类报错node、npm 认不出来装完 Node.js 后打开新终端执行node -v提示“不是内部或外部命令”这属于 PATH 没生效。常见原因有两个一是安装时没有勾选自动加入 PATH 的选项新版安装器默认勾选但老版本很多不勾二是装完没有重开终端。先在“系统属性 → 环境变量”里检查Path变量里有没有C:\Program Files\nodejs\。如果没有手动加上。再检查 npm 全局包的路径npm prefix -gWindows 上默认输出一般是C:\Users\你的用户名\AppData\Roaming\npm。这个目录也必须存在于 PATH 中否则claude命令找不到。检查方法where claude如果能输出路径说明 PATH 没问题提示找不到就把上面的 npm 全局目录加到 PATH 里然后重开终端。这里我踩过的坑是改完 PATH 一定要完全关闭终端再重新打开VS Code 里的终端也要整体重开否则读到的还是旧的 PATH。5.3 显示与编码类问题中文乱码、字符集Claude Code 输出的内容带 Unicode 字符比较多Windows 老终端conhost默认代码页不是 UTF-8就会出现中文和符号乱码。解决方法优先用 Windows Terminal然后在设置里把字体改成支持中文宽字符的比如 Cascadia Code 或 JetBrains Mono如果还在老终端里先执行chcp 65001把代码页切到 UTF-8在 PowerShell 里可以顺手设置$OutputEncoding [Console]::OutputEncoding [System.Text.Encoding]::UTF8乱码不致命但非常影响心情。我最初在默认 CMD 里跑 Claude Code输出里冒号、箭头符号全是乱码一度以为是软件坏了。换成 Windows Terminal 之后干干净净再没出现这类问题。5.4 其他高频问题速查表我把这段时间见过的高频问题统一整理成一个表方便遇到问题时快速定位现象大概率原因解决方式claude命令找不到npm 全局目录没在 PATH把npm prefix -g输出目录加入 PATH安装时报 EACCES 权限错误npm 全局目录权限不足用管理员身份运行终端重试或修正 npm 全局目录归属npm install 速度极慢、卡住默认官方源网络不稳定切换 npm 镜像源后重试运行一段时间后提示版本过期版本更新claude update或npm update -g首次运行时权限弹窗无限循环已拒绝目录访问删除%USERPROFILE%\.claude.json中对应的拒绝记录重新运行登录时浏览器没有自动弹出默认浏览器设置问题手动打开浏览器访问命令行里显示的 URL粘贴验证码VS Code 扩展连不上 CLICLI 版本过旧先升级 CLI再重载 VS Code 窗口端口或文件被占用任务执行失败杀毒软件拦截终端命令在安全软件里放行终端进程或临时暂停实时防护测试最后补充两个卸载相关的点。想彻底卸载 Claude Codenpm 方式执行npm uninstall -g anthropic-ai/claude-code然后手动删掉%USERPROFILE%\.claude目录和%USERPROFILE%\.claude.json这是它的配置和会话历史。如果是官方脚本安装的原生版本卸载方式不太一样建议直接查官方卸载说明或者重新跑安装脚本看提示。反正我踩过一次npm 删了全局包但配置还在重新安装时会读到旧配置出现奇怪的会话错乱所以卸载干净很重要。6. 我自己踩过坑之后的一些使用心得文章最后我不做什么总结就分享几个真实的体会。第一个体会是Claude Code 在 Windows 上“能用”和“好用”之间差的往往就是环境细节。开发者模式有没有开、终端是不是 Windows Terminal、PATH 有没有配置到位这三件事如果都做到位后面的体验会顺滑得多。很多人装完就跑遇到几个报错就放弃了其实多半不是工具的问题是环境的问题。第二个体会是CLAUDE.md 值得花时间好好写。它的效果是复利性质的——你写得越细AI 后续每次会话都在这些规则之上工作项目越复杂收益越明显。我建议新项目第一周就同步维护一份别等代码写多了再补那时候上下文已经乱了。第三个体会更偏使用心态把 Claude Code 当成“结对编程的实习生”不是“全自动外包”。复杂任务先切 plan 模式让它出方案你检查完逻辑再让它执行关键代码改动一定要自己 review diff。这些习惯会让你既享受到效率提升又不会被它的失误带进坑里。毕竟工具越强越需要你清楚自己在做什么。