1. 为什么要在Windows上用Claude CodeClaude Code 是 Anthropic 官方推出的命令行 AI 编程助手直接在终端里跟你对话能读代码、改文件、跑命令、提交代码相当于一个常驻在终端里的结对程序员。很多人以为这类 CLI 工具在 Windows 上会很折腾其实不完全是这样——只要把环境基础打好Windows 下一样能稳定运行有些地方甚至还能结合 Windows 特有的配置方式做得更顺手。先厘清一个概念Claude Code 和 Claude 桌面客户端不是同一个东西。Claude App 是聊天窗口式的产品Claude Code 则直接跑在你的项目目录里通过读取文件内容、分析 Git 状态、执行终端命令来辅助写代码。对于习惯键盘操作、不想频繁切换窗口的开发者来说这种工作流非常自然交互体验也更偏向“程序员之间的协作”而非“用户与客服问答”。在 Windows 上Claude Code 的典型场景有这么几类。一是日常 Git 仓库开发让它分析 diff、生成 commit message、补单元测试二是项目重构给它一个目标让它在多个文件之间做联动修改三是排障比如报错信息很诡异、依赖版本互相冲突把上下文喂给它让它带着项目环境去做推理。这三种场景在 Windows 命令行环境下都能稳定落地前提是配置得当。这篇东西适合谁读如果你已经会敲终端命令想在 Windows 下把 Claude Code 装起来正常用或者你已经装上了但经常报错想找一套完整的避坑方案——这篇文章就是按实际落地顺序写的从装环境、装工具、配置认证到接入本地模型、配合 VS Code 使用再到问题排查和性能优化每一步都可以直接照着做。2. 先把手头的环境磨利Windows 下的依赖准备2.1 Node.js 安装版本选择比装本身更重要Claude Code 是一个 npm 包装它的前提是 Node.js。这里很容易出问题的地方不是“怎么装”而是“装哪个版本”。我见过不少人随便下一个 Node 就开跑结果 npm 版本太旧装包时报一堆证书错误和依赖冲突。Claude Code 官方建议使用 Node.js 18 或更高版本我个人的建议是直接上 20 LTS 或 22 LTS这两个版本稳定性好、生态兼容度高不会跑着跑着突然跟你闹脾气。Windows 安装 Node.js 有两条主流路线。一条是去官网下载 LTS 版本的 .msi 安装包双击一路 Next这个适合大多数人。另一条是用 nvm-windows 做多版本管理适合平时要切换 Node 版本做兼容测试的人。如果你装了多个项目、每个项目要求的 Node 版本不一样我推荐 nvm-windows省得以后反复卸载安装。安装完成后有一个验证动作很关键。打开 PowerShell输入node -v和npm -v两个命令都能正常输出版本号说明基础环境已经就绪。我遇到过不少“装完了却提示 node 不是内部或外部命令”的情况十有八九是安装时没勾选“Add to PATH”选项或者安装完没有重启终端环境变量没被重新加载。注意安装 .msi 时务必确认安装向导中勾选了“Add to PATH”这一步漏了后面会很痛苦。2.2 Git 与终端准备Claude Code 的很多能力都建立在 Git 之上比如分析改动、生成提交信息、回滚错误修改。Windows 下装 Git 比较常规去官网下载安装包一路默认即可。但有一个选项值得注意在安装向导的“Line Ending Conversions”这一步建议选择“Checkout as-is, commit as-is”也就是不自动转换换行符。Windows 默认的 CRLF 自动转换在多平台协作的项目里会引发大量无意义的 diffClaude Code 在处理这些改动时会变得不知所措。终端方面我强烈建议直接装 Windows Terminal。它比老旧的 ConHost 窗口强太多支持多标签、富文本渲染、自定义主题Claude Code 的输出里有大量代码块和彩色标记在 Windows Terminal 里体验能上一个档次。装好的 Windows Terminal 默认走 PowerShell比如说你可以把默认配置文件改成 PowerShell 7体验会更好。PowerShell 7 相比 Windows 自带的 Windows PowerShell 5.1在管道处理、对象输出和 ANSI 转义序列的支持上都更现代Claude Code 输出的彩色字符不会变成乱码。还有一个经常踩的坑PowerShell 的执行策略。npm 全局安装后脚本文件要能直接执行需要给当前用户设置 RemoteSigned 执行策略。如果不做这一步运行claude时会直接报错拒绝执行脚本。在终端里执行一条命令就行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser这条命令允许运行本地脚本从互联网上下载的脚本则需要数字签名是比较平衡且安全的策略选择。3. 安装与首次启动验证3.1 用 npm 装好 Claude Code环境就绪之后安装就是一个命令的事npm install -g anthropic-ai/claude-code-g参数表示全局安装这样在任意目录下都能直接调用claude命令。安装过程如果比较慢而且本身网络环境就是正常的可以考虑用 npmmirror 的镜像源来加速这个是完全合规且常见的做法。设置镜像源的方式是npm config set registry https://registry.npmmirror.com装完之后执行claude --version验证版本。如果能正常输出类似 2.x 之类的版本号那安装这步就算过去了。如果提示claude 不是内部或外部命令首先检查 Node.js 是否真的加进了 PATH其次看 npm 全局包的存放目录是否正确。Windows 下 npm 全局目录一般在%APPDATA%\npm手动确认这个路径在系统 PATH 环境变量里。提示安装失败时不要反复重试同一个命令。先看终端报错是网络层面的、权限层面的还是依赖冲突层面的逐项排查后再重装效率高得多。3.2 首次启动与版本升级管理执行claude首次启动时它会检查当前目录是否有 git 仓库并读取项目上下文。这个时候就能明显感觉到它和聊天客户端的不同不会立刻输出一大段回答而是先进入类似 REPL 的交互模式你可以/help查看所有内置命令/status查看当前会话信息和上下文占用情况。用了一段时间后升级工具也是走 npmnpm update -g anthropic-ai/claude-code如果想精确升级到某个版本可以带版本号再装一次。卸载则是npm uninstall -g anthropic-ai/claude-code。这里提醒一句升级前最好看一眼自己的配置目录~/.claude是否会受影响。我自己遇到过升级后自定义的 CLAUDE.md 角色提示没生效的情况排查下来是权限层配置被重置了所以升级完建议先跑一次/status确认关键配置还在。4. 认证配置与全局设置4.1 登录认证的两种主要方式第一次运行claude程序会引导你完成认证。目前主流的认证方式有两种。第一种是浏览器 OAuth 登录。运行claude后选择登录终端里会显示一个 URL浏览器打开后授权你的账号终端自动完成令牌保存。这个方式适合有 Claude 账号订阅的用户整个过程很简单如果账号本身在一个组织下但组织管理员禁止了 Claude Code 访问这个方式是走不通的需要联系管理员启用权限。第二种是 API 密钥方式。去 Anthropic 控制台生成一个 API key然后通过环境变量交给 Claude Code。对应的是设置ANTHROPIC_API_KEY环境变量。这个方式适合企业用户、需要精细控制用量和成本的场景密钥本身是敏感信息别直接写进项目代码里也不要提交到 Git 仓库。注意无论用哪种方式认证状态最终会保存在本地配置目录中。不要在公用的 Windows 机器上勾选“记住我”类型的长效令牌保存避免有人拿到系统权限后直接搭车使用你的额度。4.2 环境变量的配置技巧Windows 下配置环境变量有好几种姿势最基础的是打开“系统属性”-“环境变量”新增用户级变量。这个方式配置的变量对所有终端永久生效适合一次设置好就不想再动的场景。更灵活的方式是在 PowerShell 里临时设置只对当前会话有效$env:ANTHROPIC_API_KEY 你的API密钥这种方式适合临时切换不同的密钥或配置终端一关就自动失效。我在实际使用中习惯维护一个小的 PowerShell 脚本每次开始工作前执行一次把该项目需要的环境变量一次性都配好。比改系统环境变量更可控也便于在多个项目之间切换不同的模型配置。另外Claude Code 支持项目级的配置文件。在项目根目录放一个.claude/settings.json可以指定模型参数、权限开关、自定义 MCP 服务器等等。这里的配置权限高会覆盖全局的默认配置。所以如果你发现某个设置改了全局文件不起作用可以看看项目里是不是有局部的 settings.json 在“盖楼”。5. 高级玩法接入本地模型LM Studio5.1 为什么值得接本地模型很多人在 Windows 上真正开始折腾 Claude Code是因为想把模型切换到本地。这个需求很实际某些场景不适合把代码发给第三方大模型处理或者就是单纯想用免费的开源模型跑一些简单任务比如格式转换、命名建议、代码格式化。Claude Code 早就考虑了这种需求它支持通过环境变量修改 API 地址指向任何兼容 Anthropic API 协议的服务端。LM Studio 正好能扮演这个角色。它是一个在本地运行开源大模型的图形化工具支持一键下载多种开源模型Qwen 系、Llama 系等、加载模型并启动一个本地 HTTP 服务。在 Windows 下跑 Claude Code 时接入 LM Studio本质上就是把推理计算从云上搬到本地代码不离开你的机器隐私上更有底。5.2 LM Studio 服务端的搭建LM Studio 的安装比较省心去官网下载安装包Windows 上直接双击安装。装好后需要做的核心事情就是三件在“Search”页面搜索并下载一个模型。国内网络环境下能正常访问的模型托管渠道有不少镜像分流正常操作即可。在 “Local Server” 页面点击启动服务默认端口是1234协议是 OpenAI 兼容格式但 Claude Code 也认这个套路。确认服务状态浏览器访问http://localhost:1234/v1/models能看到模型列表说明服务已经通了。这里有个细节值得留意LM Studio 启动服务时是可以换端口的但 Claude Code 的配置里你要小心地对应好。我习惯固定用1234少记一个变量。5.3 在 Claude Code 中切换本地模型切换本地模型的核心玩法是设置两个环境变量。先关掉已经打开的claude会话然后在 PowerShell 里执行$env:ANTHROPIC_BASE_URL http://localhost:1234 $env:ANTHROPIC_AUTH_TOKEN lm-studioANTHROPIC_BASE_URL让 Claude Code 不再连接官方服务的地址而是指向本地的 LM StudioANTHROPIC_AUTH_TOKEN这个令牌本身并不重要但需要一个非空值否则请求会掉进认证失败分支。设置完成后运行claude它就会通过本地模型回复。有一点必须提前说清楚本地开源模型的能力上限和 Claude 官方旗舰模型不在一个档次如果你拿本地模型去处理复杂的多文件重构任务大概率会碰壁。所以这个玩法的定位是“轻量任务 敏感代码 省钱”不适合硬扛大工程。我列一张简单的对比表方便你对号入座对比项官方模型LM Studio 本地模型复杂代码理解和重构能力强较弱数据隐私代码经过第三方服务代码不出本机成本按量计费仅耗电配置复杂度低中适合场景核心开发任务简单问答、格式化、脱敏数据6. 与 VS Code 配合的实战姿势6.1 在 VS Code 里调用 Claude Code 的几种方式VS Code 本身就是 Windows 开发者的大本营Claude Code 和它组合起来几乎是天然的搭档。最朴素的方式就是把 VS Code 自带的集成终端打开直接跑claude这样左边是代码右边是 Claude Code 的交互界面不用切换窗口。更进阶的方式是安装官方扩展或社区扩展让 Claude Code 直接以面板形式嵌入 VS Code 侧边栏。打开扩展市场搜索“Claude Code”能出现好几个结果注意筛选靠谱的。装了扩展之后选中一段代码右键发给 Claude或者让它对当前文件做 Review交互体验确实比纯终端更顺手。还有一个思路是使用 VS Code 的任务系统。在.vscode/tasks.json里预定义一个监听任务让 Claude Code 在指定终端中自动启动并加载当前项目配置。这个玩法前期配置成本稍高但适合团队内部统一开发环境——每个成员打开这个仓库时CtrlShiftB 一键就能拉起带项目上下文的 Claude Code。提示VS Code 集成的本质还是调用本机的claude可执行文件。如果你配置了本地模型改了ANTHROPIC_BASE_URL那 VS Code 里的 Claude Code 面板同样也会走本地模型不存在“面板用一个模型、终端用另一个模型”的独立机制——除非你分别设了不同的环境变量。6.2 一套顺手的日常开发工作流我实际在 Windows 下跑通的日常流程大致是这样的。准备开发任务前先在 VS Code 打开项目目录Ctrl唤出终端跑claude。进入交互界面后我的第一个操作通常是先让 Claude Code 读一遍项目的 CLAUDE.md 或 README把背景信息建立起来。然后开始干活让它写核心函数、生成单元测试、分析当前分支的改动点。遇到报错时我习惯直接把终端里的报错信息粘贴进去同时告诉 Claude Code 最近改动涉及的文件有哪些。它能结合 git diff 快速定位这个能力在排查自己刚写坏的代码时特别有用。跑完一轮修改后我会让它把改动的文件列一遍自己再审查一遍 diff确认没问题后再提交。这套工作流还有一个容易忽略的点在写长任务时Claude Code 的上下文窗口会被塞满表现为回答质量明显下降、开始重复输出。这时候不应该硬着头皮继续聊而是用/compact压缩历史会话或者干脆/clear清空当前上下文再补一段最新的项目状态描述。这个习惯能大幅提升长会话中的输出稳定性。7. Windows 下的避坑实录7.1 高频报错逐个拆在 Windows 上跑 Claude Code报错基本集中在下面这几类。第一类“claude 不是内部或外部命令”。前面说过了主要是 PATH 问题但也可能是 npm 全局目录本身就没建好。检查方法很简单直接执行npm root -g看看全局包的路径是否存在同时确认这个路径在系统 PATH 里。第二类PowerShell 拒绝运行脚本。报错内容里通常出现UnauthorizedAccess或者“禁止运行脚本”字样的提示。原因就是执行策略没放开执行前面提到的Set-ExecutionPolicy命令即可。说句题外话这里的策略设置只影响本地交互式脚本的执行不影响你的系统安全级别。第三类以管理员权限启动导致 Windows 守护进程异常。这个报错原文类似error: start the windows daemon from a non-elevated terminal; shared clients...意思是你别用“以管理员身份运行”的终端来启动 Claude Code。Windows 下某些后台服务在提升权限的终端里反而启动失败。解决方式很简单用普通权限打开终端再运行claude不要在管理员窗口里跑这类交互式编程助手。这个坑我踩了整整一个下午才反应过来。第四类组织账号访问被禁用。报错类似your organization has disabled claude subscription access for claude code。这个不是环境问题是你的账号归属组织在策略层面禁止了 Claude Code需要用个人账号或请组织管理员开通访问。技术层面没有绕行方案也别想着绕过该走流程走流程。7.2 性能与体验优化三板斧环境跑通之后有几件小事能让体验再上一个台阶。第一件是让 CLAUDE.md 发挥作用。在项目根目录下的.claude/CLAUDE.md里用自然语言写清楚项目约定比如技术栈、构建命令、代码风格、禁止改动哪些文件。Claude Code 每次启动会话都会自动加载这个文件它相当于给模型一份“项目说明书”能大幅减少低质量回复。注意不要把敏感信息写进去毕竟这个文件会跟着代码仓库走。第二件是给终端装一个好字体。代码输出里的对齐和缩进在等宽字体下才好看Windows 终端默认的字体在渲染中文和符号时经常挤在一起。换成 “Cascadia Code” 或 “Sarasa Term” 这类等宽字体阅读体验会舒服很多。第三件是控制上下文膨胀。常跑大项目的人都有体会会话越长Claude Code 的思考时间越长、输出越拖沓。日常使用中把/compact当成一个常规操作不要心疼丢掉的细节把你关心的核心约束重新写一遍翻新会话效果比带病跑完整个任务好得多。8. 常见问题速查表8.1 按症状快速定位以下问题都是我亲身踩过或在社区常见反馈里见过的整理成对照表遇到问题先看症状再动手别上来就卸载重装。症状首要排查项次要排查项命令找不到 claudePATH 是否包含 npm 全局目录Node.js 是否装成功安装超时 / 下载卡住npm 源是否走镜像防火墙是否拦截 CLI 请求首次运行报认证失败浏览器 OAuth 是否真正授权完成API key 是否复制了多余空格中文显示乱码终端是否用 UTF-8Windows Terminal 字体是否支持中文对话中途变笨上下文窗口是否快满了是否该/compact一次本地模型不生效ANTHROPIC_BASE_URL 端口是否对LM Studio 服务是否还在跑写完代码不保存到文件是否开启了只读模式权限设置是否限制写入目录升级后配置没了检查 ~/.claude 是否被覆盖项目级 settings 是否覆盖全局8.2 通用排查顺序建议如果遇到的是没有明确头绪的怪问题我建议按“网络层 - 配置层 - 上下文层”的顺序排查这套方法论在 Windows 下尤其见效。先确认网络层在终端里跑ping api.anthropic.com之类的连通性测试判断是不是网络问题这一步我们先只讨论在正常可访问环境下的情况。再确认配置层claude /status看当前用的模型、认证方式、API 地址尤其是你是不是忘了切换回官方地址导致一直打本地模型。最后看上下文层会话是不是已经长到老天爷来了也救不回来的程度是就/clear。如果还是没解决别耗着。把 Claude Code 的日志目录翻出来看Windows 下一般在~/.claude/logs直接把最近的日志文件贴给 AI 助手让它辅助分析。自己一行行看日志效率极低但这个文件信息量是最大的。最后说一点个人体会Claude Code 这个工具用顺手的核心从来不是“装得多完美”而是“和自己的工作流融得多自然”。我在 Windows 下真正觉得它值钱是在把项目级 CLAUDE.md、本地模型切换、VS Code 集成这三样都理顺之后它才从“一个会聊天的终端玩具”变成了“一个真的能帮你干活的搭档”。如果你也正在这个工具上投入时间别急着追求新特性先把这几个基础环节打磨好收获会远超预期。