很多写代码的朋友应该都有这种感觉:工具链越来越重,IDE 越来越臃肿,但真正想解决一个具体问题时,反而要在菜单里翻半天。Claude Code 这种跑在终端里的 AI 编程代理,正好戳中了这个痛点——它不跟你抢编辑器,不搞花哨界面,直接在命令行里读你的项目代码、改文件、跑命令、提交代码,像雇了一个随叫随到的结对程序员。这篇文章是给 Windows 用户写的,我把自己从零开始安装、配置、跑通第一个任务的完整过程,踩过的坑、绕过的弯,全记录在这里。不管你是刚接触终端命令的新手,还是用惯了 Linux/macOS 的老手想看看 Windows 上怎么玩,照着走一遍应该都能跑起来。
先说清楚它能干什么:你给它一个任务,比如“把这个接口的单元测试补全”,它会自己翻项目结构、读相关文件、生成或修改代码、运行测试,然后告诉你改了什么、下一步建议做什么。整个过程在终端里完成,既能直接接管,也能每步确认。它不是 IDE 插件那种“补全代码”的层次,而是真正理解项目上下文的编码 Agent。
适合谁来参考?用 Windows 做开发、又想体验 AI 编程代理的人,工作上需要在多台 Windows 机器快速部署环境的人,以及踩了一堆错正准备放弃的人。这篇不是官方文档的翻译,是我实际装完、用起来之后,按顺序整理的一份可复现清单。
1. 安装前的环境准备
1.1 检查 Windows 版本与权限
先把底座弄明白。Claude Code 官方支持 Windows 10/11,但我实际测下来,Windows 11 的体验最顺,Windows 10 旧版本偶尔会在终端交互和文件监听上有小毛病。建议先确认几个前提:
- 系统版本尽量新,Windows 10 也至少是 22H2 之后的版本
- 建议使用 Windows Terminal,而不是老旧的 conhost 窗口
- 安装过程需要管理员权限,但日常使用普通权限就行
- 磁盘剩余空间至少 2GB(Node.js 运行时 + 缓存 + 项目环境留出余量)
权限这块有个容易忽略的点:如果你用的是公司统一分发的电脑,可能有软件安装策略限制,npm 全局安装目录会被重定向,装完命令找不到。这时候优先检查当前用户是否有 C 盘用户目录的写入权限,npm 默认装到 %APPDATA%\npm 下,只要这个目录能写,就有很大概率能绕开管理员限制。
1.2 Node.js 与 npm 的版本要求
Claude Code 是 npm 包,Node.js 是它的运行底座。版本要求是 Node.js 18+,但我个人建议直接上 20 LTS 或 22 LTS。原因不是玄学:旧版本 Node 的 fetch、Web Stream 等 API 实现不完整,Claude Code 在流式输出和长任务处理时容易出现中断或内存问题,新版本稳很多。
安装 Node.js 有两种常见路径,官方安装包和 Windows 包管理器 winget:
bash复制winget install OpenJS.NodeJS.LTS
装完务必开一个新的终端窗口,然后验证版本:
bash复制node --version
npm --version
我遇到过很多次“明明装完了却提示找不到 node”,十有八九是终端会话没有重启,PATH 环境变量没刷新。另外提醒一句:如果你机器上已经装了 nvm-windows 之类的版本管理工具,请先用 nvm list 确认当前激活的版本,别装完 A 版本结果 shell 里用的是 B 版本,排查半天才发现是版本没切过来。
1.3 更新 PowerShell 执行策略
这是 Windows 上最容易卡住新手的一步。Claude Code 装完之后,需要运行 claude 命令启动,但 PowerShell 出于安全考虑,默认禁止执行来自网络的脚本,会直接报红字:
text复制无法加载文件 ...因为在此系统上禁止运行脚本
解决办法是在管理员权限的 PowerShell 里修改执行策略:
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
解释一下 RemoteSigned 的含义:本机创建的脚本可以运行,从网上下载的脚本必须有可信签名。Claude Code 安装时生成的启动脚本正是本次安装产生的,属于允许范围。这个策略只对当前用户生效,不会影响系统全局,安全性和便利性之间是比较合理的平衡。
改完验证一下:
powershell复制Get-ExecutionPolicy -List
看到 CurrentUser 那一行是 RemoteSigned 就对了。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 核心安装流程:从 npm 安装到首次启动
2.1 使用 npm 全局安装 Claude Code
环境就绪后,安装命令本身反而最简单。打开终端(PowerShell 或 Windows Terminal 都行),执行:
bash复制npm install -g @anthropic-ai/claude-code
这里要留意几个安装细节。npm 全局安装会输出安装日志,如果网络不稳定,容易遇到 ETIMEDOUT、ECONNRESET 这类错误,这时候可以配置 npm 国内镜像源(例如淘宝镜像),速度会有明显提升:
bash复制npm config set registry https://registry.npmmirror.com
装的时候它会自动拉取原生模块,如果杀毒软件拦截了脚本执行,装完会出现“命令存在但运行毫无反应”的情况。我建议安装过程中暂时关掉实时防护,或者至少把 npm 目录加入白名单,装完再恢复。
安装完成后确认版本:
bash复制claude --version
这一步能显示出版本号,基本就没问题了。如果提示“claude 不是内部或外部命令”,大概率还是 PATH 问题,把 %APPDATA%\npm 加入系统 PATH 再重开终端。
2.2 首次启动:登录认证的两种方式
运行 claude 命令后,第一次启动会进入登录流程。目前主流是两种认证方式:账号 OAuth 登录和 API Key 登录。
OAuth 登录适合 Claude 订阅用户(Pro/Max)。启动后选择“授权”,终端会给出一个链接,用默认浏览器打开,登录你的 Claude 账号并授权。授权成功后回终端看,会自动完成认证并进入交互界面。我实测这个过程在 Windows 上偶尔会出现浏览器没弹出来的情况,解决办法是手动复制终端里的链接到浏览器打开,不用非得等它自动弹。
API Key 方式适合按量付费用户。在 Anthropic 控制台创建一个 API Key,启动后选择“粘贴 API Key”,把以 sk-ant-... 开头的密钥贴进去即可。这里有个很重要的经验:API Key 的权限和额度跟订阅账号是两套体系,别混着用。我见过有人订阅了 Claude Max 却跑去创建 API Key 来登录,结果额度用完了还不知道原因。
2.3 快速验证安装是否成功
认证通过后,你会看到类似这样的交互界面:
text复制Claude Code
>
这就已经进来了。先用一个最小的任务验证整体链路,我建议你可以直接问我:
text复制请用中文打个招呼,并告诉我当前目录下有哪些文件
如果正常返回了中文问候语,并列出文件列表,说明安装、认证、模型调用全链路是通的。这一步比任何 Hello World 都实在,因为它同时验证了会话连接和本地文件系统读取能力。
注意:首次启动会询问一些配置选项(比如是否开启统计、是否自动更新),没有特殊需求全部选默认即可,后面可以随时改配置。
3. 在真实项目里跑通第一个任务
3.1 如何正确进入项目目录
Claude Code 是“目录即上下文”的工具,你在哪个目录启动它,它就认为你在操作哪个项目。最忌讳的是在用户主目录 C:\Users\xxx 下直接启动,然后让它“找到我的项目”——它确实能找到,但扫描范围过大,响应变慢,还可能不经你确认就改错文件。
正确姿势是先切到项目根目录,再启动:
bash复制cd D:\projects\my-web-app
claude
启动后可以用 /status 命令确认当前工作目录是否正确。我还习惯在启动前用 ls 看一眼目录内容,确认没进错文件夹。
3.2 实际任务演示:修改代码并运行测试
为了让你有体感,我给你看一段我实际在 Windows 上跑过的流程。假设我手里有个 Node.js 项目,src 目录下有个工具函数文件,我启动 Claude Code 后输入:
text复制看一下 src 目录下的 utils.js,找出里面日期格式化函数的 bug,修复它,并告诉我改了什么
它的行为大致是这样:
- 读取
src/utils.js文件内容 - 定位到日期格式化函数的缺陷逻辑
- 用 diff 形式展示修改方案,等你确认
- 确认后写入文件
- 检查是否有相关测试文件,建议运行测试
这里有个 Windows 下很实用的操作:你不需要把所有工作都交给它自动执行。在它准备修改文件之前,默认会请求确认,这个机制在 Windows 上特别重要——因为 Windows 的文件锁定行为比 Unix 严格得多,如果某个文件正被编辑器占用,写入会失败。
3.3 利用 CLAUDE.md 注入项目规范
用上一两次之后,你会发现每次都要重新向 Claude Code 解释项目结构和技术栈,太啰嗦。解决方案是在项目根目录创建一个 CLAUDE.md 文件,它相当于项目级的“说明书”,Claude Code 每次启动都会自动读取它。
我自己的模板通常包含这几块:
markdown复制# 项目说明
这是一个基于 Express + React 的内部管理系统
# 技术栈
- 后端:Node.js 18, Express 4
- 前端:React 18, Vite
- 数据库:PostgreSQL 15
# 常用命令
- 开发启动:npm run dev
- 测试运行:npm test
- 构建:npm run build
# 代码规范
- 使用 ES Module,不使用 CommonJS
- 错误处理必须返回统一的 { code, message } 结构
- 所有日期时间使用 UTC 存储
写完之后,每次在这个目录启动 Claude Code,它都会自动带上这些上下文。比如你让它“新增一个用户查询接口”,它就不会问你“用的是什么框架”,而是直接按 Express 的路由风格写代码。
3.4 多项目切换时的会话管理
Windows 下开多个项目窗口很常见。Claude Code 支持会话恢复功能,用 claude --continue 可以接着上一个会话,claude --resume 可以选择恢复某一个历史会话。我个人的习惯是每个项目单独开一个终端窗口,用 claude --continue 继续当天的任务,这样每个窗口的上下文都只聚焦一个项目,不会串味。
如果不想继续某个会话,在交互界面输入 /clear 可以清空当前会话上下文,重新开始。这个命令在切换任务时非常实用,比新开窗口更省事。
4. 常见报错与排查技巧实录
4.1 执行策略禁止脚本
报错特征:
text复制claude.ps1 无法加载,因为在此系统上禁止运行脚本
原因和处理方法我在前面已经提过,这里再补充一个细节:如果你用的是 Windows 自带的 PowerShell 5.1,执行策略需要单独设置;如果你用的是 PowerShell 7+(通常命名为 pwsh),它是独立的配置。两边都得设一遍,只设一边的话,换终端又报错。
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
设置后立刻生效,不需要重启终端。
4.2 模型不识别或版本不支持
报错特征:
text复制"deepseek-v4-pro" is not a model this version of claude code recognizes
这个报错我见得非常多,包括在社交媒体上也是高频问题。核心原因其实很简单:Claude Code 本身是不断迭代的,老版本内置的模型名单里没有新模型,而配置文件中又指定了那个模型,启动时就会直接不认账。
排查思路:
- 确认 Claude Code 版本,
claude --version,太旧就更新:npm update -g @anthropic-ai/claude-code - 检查模型配置是否通过环境变量或配置文件指定了不存在的名字
- 用
/model命令查看当前可选模型列表
这里延伸出一个常见用法:通过环境变量指定第三方兼容 API 的模型。比如接入 DeepSeek 时,有人会设置 ANTHROPIC_MODEL 之类的变量。但模型名称必须写对,写错就会触发上面这个报错。我建议先在配置面板里确认模型 ID,再写到环境变量里,不要凭记忆敲。
4.3 WSL 环境提示版本过旧
报错特征:
text复制适用于 Linux 的 Windows 子系统必须更新到最新版本才能继续
这个报错一般不是出在 Claude Code 本身,而是你可能在 WSL 里也装了一份 Claude Code,或者某些功能试图调用 WSL 环境。Windows 端如果检测到 WSL 版本过旧,会提示更新。
解决办法:
bash复制wsl --update
这条命令会从微软服务器拉取最新的 WSL 内核。如果提示更新失败,检查一下 Windows 系统更新服务是否被禁用,或者手动从微软官网下载 WSL 更新包。
4.4 组织订阅被禁用
报错特征:
text复制your organization has disabled claude subscription access for claude code
这个问题的根源是账号权限而非技术故障。如果你用企业邮箱注册的 Claude 账号登录,组织管理员可能在后台关闭了 Claude Code 的访问权限。这时候你个人订阅的 Pro/Max 权限不一定能生效,视组织的策略而定。
解决办法:
- 联系 IT/管理员,确认是否开放 Claude Code 权限
- 如果等不及,可以换成个人邮箱账号登录,或者使用 API Key 方式
- 尽量避免在工作目录下混淆不同账号的配置缓存
4.5 安装成功但命令无响应
这个现象在 Windows 上特别容易被人忽略:安装日志看着全绿,claude 命令敲下去也进入了,但输入问题后长时间无响应,最后超时。
排查步骤:
- 检查账户余额/订阅状态,是否已过期或被限流
- 检查网络是否能正常访问 API 服务,可以借助代理或调整网络环境(在合法合规的前提下)
- 检查防火墙/安全软件是否拦截了 Node.js 进程的外连请求
- 用
/status查看当前认证信息,确认用的哪个账号
我遇到过一种很隐蔽的情况:系统代理开着,但终端里没有配置代理环境变量,HTTP 请求走了代理失败,超时半天。这时候在终端里同步设置代理环境变量,问题立刻解决。具体怎么配,取决于你公司或自己用的代理方案,不要照着网上抄,要看你自己的实际网络环境。
4.6 常见问题速查表
| 问题现象 | 可能原因 | 快速处理 |
|---|---|---|
| 安装报 ETIMEDOUT | 网络原因 | 切换 npm 镜像源重试 |
| 启动报执行策略错误 | PowerShell 策略限制 | 执行 Set-ExecutionPolicy 命令 |
| 模型不识别 | 版本过旧或配置错误 | 更新版本并核验模型 ID |
| 长时间无响应 | 订阅额度/网络问题 | 检查账号状态和代理配置 |
| 文件写入失败 | 文件被占用 | 关闭占用文件的编辑器后重试 |
| 输出中文乱码 | 终端编码问题 | 在终端设置中切换 UTF-8 编码 |
| WSL 版本过旧 | WSL 内核未更新 | 运行 wsl --update |
| 命令找不到 | PATH 未配置 | 添加 %APPDATA%\npm 到 PATH |
5. 进阶配置与个人经验分享
5.1 第三方模型接入的注意事项
顺着前面模型不识别的问题,多说一些。Claude Code 现在支持通过环境变量把模型请求转发到兼容 Anthropic API 的第三方服务(比如 DeepSeek 等国产模型服务),形式大致是这样:
bash复制set ANTHROPIC_BASE_URL=https://api.xxx.com
set ANTHROPIC_MODEL=deepseek-chat
set ANTHROPIC_API_KEY=你的key
设置完成后重新启动 claude。但这里必须提醒几句:
- 第三方模型的工具调用能力参差不齐,有些模型没经过 Agent 场景优化,跑到一半会“假装调用工具”但不真正执行,或者输出格式不对,导致 Claude Code 卡住
- 模型必须支持 tool use 功能,否则很多自动化子任务无法完成
- 第三方服务的稳定性直接决定你的体验,建议先在简单任务上验证,再投入实际项目
我自己试了一圈下来的体会是:如果你只是想体验一下,可以拿低价模型跑跑看;但正式干活、尤其是涉及大规模重构和自主修改文件的场景,官方模型的差距还是明显。这个结论不绝对,模型迭代很快,但就目前而言,工具调用质量和上下文理解能力是硬门槛。
5.2 终端体验优化
Windows 原生终端的体验,说实话跟 macOS 的 iTerm2 还有差距,但用 Windows Terminal 已经能弥补大部分。我做了几个小优化,体验提升很明显:
- 字体换成 Cascadia Code 或 JetBrains Mono,等宽字体下对齐好看很多
- 开启自动换行和缓冲区加大,输出长日志时不至于来回滚动
- 把终端背景色调成深色,Claude Code 的高亮信息对比度更清晰
- 给
claude命令配置一个别名,比如cc,日常进入快很多
Windows Terminal 的配置文件在设置界面可以直接改,不需要手写 JSON,对新手友好。
5.3 几个我觉得很有用的内置命令
Claude Code 自带一些斜杠命令,说三个我最常用的:
/clear:清空当前会话上下文,换任务时用/compact:压缩历史对话,上下文太长时能续命/cost:查看当前会话消耗的 token 估算,控制预算有用
5.4 实际工作中的使用边界
最后说点实在的。Claude Code 很强,但不是万能的。我在 Windows 上实际用了几个月,总结出几个适合它干的事和不适合它干的事:
适合:
- 写单元测试、修 bug、做代码重构
- 解释陌生项目的代码结构
- 生成接口文档、写 commit message
- 批量替换代码模式
不太适合:
- 需要频繁操作 Windows GUI 的任务(它还做不到控制鼠标键盘)
- 涉及大型二进制包下载和构建的任务(容易卡住)
- 需要严格安全审计的敏感生产环境(建议只读模式或人工审核)
我自己的使用习惯是:小步快跑,每个任务都让它给出明确的修改计划,执行前人工审核 diff,执行后跑一遍测试再继续下一步。这样既不丧失效率,也保留了程序员的判断力。
这个工具往后还有不少可玩的方向,比如结合项目模板生成整套工程骨架、接入团队内部接口文档作为上下文、配合定时任务做自动化代码体检。不过对刚接触的人而言,先把安装跑通,在真实项目里体验一两次“AI 帮你改代码”的流程,比研究任何高级玩法都更有价值。
