1. 为什么要在 Win11 本地跑 Claude CodeClaude Code 是 Anthropic 推出的命令行 AI 编程助手它跟网页版聊天最大的区别在于它能直接读写你本地的项目文件、执行终端命令、跑测试、改代码相当于一个坐在你电脑旁边的结对程序员。很多人第一次听说它以为必须联网用云端环境其实它完全可以跑在本地 Win11 机器上配合 VSCode 的可视化界面体验比纯终端舒服得多。我自己的主力机就是 Win11从零到跑通大概花了四十分钟中间踩了几个坑主要是 Node.js 版本和 Git 路径的问题。这篇就把整个流程拆开讲清楚包括环境准备、安装配置、VSCode 集成、常见报错排查尽量让完全没接触过命令行的朋友也能跟着做下来。适合谁看一是想在本地用 AI 辅助写代码但不想折腾 Linux 的 Windows 用户二是已经装了 VSCode 但不知道怎么把 Claude Code 接进去的人三是环境配置老是出问题、想找一份靠谱清单的开发者。下面所有步骤都在 Win11 23H2 和 24H2 上实测过理论上 Win10 也能用但本文以 Win11 为准。2. 环境准备Node.js、Git 与终端选择2.1 Node.js 装哪个版本才不踩坑Claude Code 是基于 Node.js 运行的工具所以第一步必须把 Node.js 装好。这里有个关键点不要装太老的版本。官方要求 Node.js 18 及以上我实测 18.x 能用但更推荐直接上 20 LTS 或 22 LTS因为 18 在某些模块导出上会报does not provide an export named这类错误尤其是你项目里混用了 ESM 和 CJS 的时候。下载渠道就一个Node.js 官网。打开后选 LTS 版本Windows 安装包是.msi格式双击一路下一步即可。安装时注意勾选Add to PATH这个默认是勾上的别手贱取消。装完之后验证node -v npm -v两条命令都能输出版本号说明装好了。如果提示不是内部或外部命令说明 PATH 没生效重启一下终端或者注销重登。提示如果你之前装过 Node.js建议先用where node看看是不是有多个版本冲突。Windows 上常见的是同时装了 nvm-windows 和官方安装包导致版本混乱。这种情况先卸载干净再重装。2.2 Git 安装与基础配置Claude Code 很多功能依赖 Git比如查看文件改动、生成 diff、提交代码。所以 Git 也得装。去 Git 官网下载 Windows 版安装时有个选项叫Adjusting your PATH environment选第二项 Git from the command line and also from 3rd-party software这样 Git 命令才能在任意终端里用。装完验证git --version然后做两件基础配置不然后面提交代码会报错git config --global user.name 你的名字 git config --global user.email 你的邮箱如果你用 Gitee 或 GitHub还需要配 SSH 密钥。生成密钥的命令ssh-keygen -t ed25519 -C 你的邮箱一路回车密钥默认存在C:\Users\你的用户名\.ssh\下。把id_ed25519.pub里的内容复制到 Gitee 或 GitHub 的 SSH 设置里就行。这一步不是必须的但如果你想让 Claude Code 帮你推送代码配好会省很多事。2.3 终端选 PowerShell 还是 Windows TerminalWin11 自带的终端有两个传统的 PowerShell 和新的 Windows Terminal。我强烈建议用Windows Terminal它支持多标签、字体渲染好、复制粘贴顺手而且能直接调 PowerShell 或 CMD。Win11 默认右键在终端中打开就是它。如果你习惯老式右键菜单Win11 那个折叠菜单确实烦可以改回 Win10 风格打开注册表编辑器定位到HKEY_CURRENT_USER\Software\Classes\CLSID新建项{86ca1aa0-34aa-4e8b-a509-50c905bae2a2}再建子项InprocServer32默认值留空重启资源管理器即可。这个操作跟 Claude Code 没直接关系但能让你打开终端更顺手。3. Claude Code 安装与首次配置3.1 安装命令与目录结构Node.js 和 Git 都就绪后安装 Claude Code 就一行命令npm install -g anthropic-ai/claude-code-g表示全局安装装完之后claude命令在任何目录都能用。安装过程会从 npm 源拉包国内网络可能慢可以临时换源npm config set registry https://registry.npmmirror.com装完验证claude --version能输出版本号就成功了。如果报权限错误用管理员身份打开终端再装一次。Windows 上偶尔会遇到 npm 全局目录没权限的问题可以改一下全局路径npm config set prefix C:\Users\你的用户名\AppData\Roaming\npm这个目录默认就在 PATH 里改完重装即可。3.2 首次启动与登录方式在任意项目目录下输入claude第一次启动会引导你登录。Claude Code 支持两种方式一是用 Anthropic 账号登录会跳转浏览器授权二是用 API Key。如果你有 API Key直接设置环境变量setx ANTHROPIC_API_KEY 你的key设置完要重开终端才生效。登录成功后你会看到一个交互式界面可以直接用自然语言让它干活比如帮我看看这个项目结构、给这个函数加个单元测试。注意API Key 不要硬编码在代码里也不要在截图里露出来。用环境变量是最稳妥的方式。如果你在团队里共用机器建议用单独的配置文件管理。3.3 项目初始化与 CLAUDE.md进入一个项目后第一件事是让它生成项目说明文件。Claude Code 有个约定项目根目录下的CLAUDE.md是它的记忆文件里面写清楚项目结构、技术栈、编码规范它每次启动都会读。你可以手动写也可以让它自己生成claude /init/init命令会扫描项目自动生成一份CLAUDE.md。生成后建议自己再改改把常用的构建命令、测试命令、代码风格要求写进去。比如## 构建 npm run build ## 测试 npm test ## 规范 - 使用 TypeScript - 组件用函数式写法 - 提交信息用中文这份文件越详细Claude Code 干活越贴合你的习惯。我自己的项目里还会把数据库连接方式、环境变量说明写进去省得每次重复解释。4. VSCode 可视化界面集成4.1 VSCode 安装与中文设置纯终端用 Claude Code 没问题但看代码改动、对比 diff 还是图形界面舒服。VSCode 去官网下载 Windows 版安装时勾选添加到 PATH和将通过 Code 打开操作添加到资源管理器目录上下文菜单这样右键文件夹就能直接打开。装完第一件事是设中文按CtrlShiftP输入Configure Display Language选zh-cn重启即可。如果列表里没有中文去扩展市场搜 Chinese 装官方语言包。4.2 安装 Claude Code 扩展VSCode 扩展市场里搜 Claude Code找到 Anthropic 官方发布的那个装。装完后左侧活动栏会出现一个 Claude 图标点开就是对话面板。这个面板跟终端里的 Claude Code 是打通的你在面板里发的指令它同样能读写项目文件。扩展装好后需要配置一下。打开设置搜 claude找到 API Key 或登录相关选项。如果你已经在终端登录过扩展通常会自动识别。如果没有手动填 API Key 或者点登录按钮走浏览器授权。提示扩展和终端版本要匹配。如果你终端里claude --version是 1.x扩展也更新到最新避免协议不兼容导致连不上。4.3 在 VSCode 里跑通第一个任务配置完成后在 VSCode 里打开一个项目文件夹点开 Claude 面板输入帮我看看这个项目用了哪些依赖列个清单它会自动读取package.json或requirements.txt把依赖列出来。再试一个给 src/utils/format.js 里的 formatDate 函数加个边界处理它会打开文件、定位函数、给出修改建议你确认后直接应用。整个过程不用切终端改动也能在编辑器里直接看到 diff比纯命令行直观很多。如果你想让 Claude Code 在 VSCode 内置终端里跑也可以按Ctrl打开终端直接输claude效果一样。两种方式看个人习惯我一般是面板和终端混用探索性任务用面板需要跑命令的时候切终端。5. 常见问题与排查技巧实录5.1 安装与启动阶段的报错问题一npm install卡住或超时。国内网络访问 npm 官方源慢是常态。换淘宝镜像源或者用npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com临时指定。如果公司网络有代理需要先配npm config set proxy和https-proxy。问题二claude命令找不到。九成是 npm 全局目录没在 PATH 里。用npm config get prefix看全局目录在哪然后手动把这个路径加到系统环境变量 Path 里。改完重开终端。问题三Node.js 版本报错does not provide an export named。这是 18.x 的已知问题升级到 20 LTS 以上即可。升级前先卸载旧版再装新版别直接覆盖。问题四Git 相关命令报错。检查git --version是否正常以及项目目录是不是 Git 仓库。如果不是先git init。Claude Code 在非 Git 目录下也能用但 diff 和回滚功能会受限。5.2 使用过程中的典型故障问题五Claude Code 读不到文件。检查你是不是在项目根目录启动的。它默认只操作当前工作目录及子目录如果你在C:\Users\你下启动它看不到 D 盘的项目。用cd切到项目目录再启动。问题六改动没生效或冲突。Claude Code 改文件前会给你看 diff确认后才写入。如果你同时用其他工具改了同一个文件可能冲突。建议操作前先git commit一次出问题直接git checkout .回滚。问题七VSCode 扩展连不上。先确认终端里claude能用。如果终端正常但扩展不行检查扩展版本、重启 VSCode、看输出面板的日志。常见的是 API Key 没配或过期。问题八中文乱码。Windows 终端默认编码可能是 GBK导致中文输出乱码。在 PowerShell 里执行chcp 65001切到 UTF-8或者在 Windows Terminal 设置里把默认编码改成 UTF-8。5.3 常见问题速查表现象可能原因解决方法npm 安装超时网络源慢换 npmmirror 源claude 命令找不到PATH 未配置把 npm 全局目录加入 PathNode 版本报错版本过低升级到 20 LTS 以上读不到项目文件启动目录不对cd 到项目根目录再启动扩展连不上Key 未配或版本不匹配检查 Key、更新扩展中文乱码终端编码非 UTF-8chcp 65001 或改终端设置5.4 几条实操心得第一先 commit 再让 AI 改代码。这是血泪教训。Claude Code 虽然会给你看 diff但批量改动时你未必看得过来。养成习惯动手前git add . git commit -m before ai出问题一键回滚心里踏实。第二CLAUDE.md 值得花时间写。很多人跳过这步结果每次都要重复解释项目背景。花十分钟写清楚技术栈、目录结构、常用命令后面能省几十次重复沟通。第三别让它碰敏感文件。项目里的.env、密钥文件、生产配置最好在CLAUDE.md里明确写不要修改这些文件。它虽然会遵守但提前说清楚更保险。第四大任务拆小。让它一次改十个文件出错概率高。拆成先改这个函数、再改那个模块每步确认质量更稳。第五Win11 的自动更新有时候会打断长任务。如果你在跑一个耗时较长的重构建议先暂停自动更新或者把任务拆短。这个跟 Claude Code 无关但确实影响体验。6. 进阶玩法与效率提升6.1 自定义命令与快捷操作Claude Code 支持自定义斜杠命令。在项目里建.claude/commands/目录每个.md文件就是一个命令。比如建一个review.md请审查当前 Git 暂存区的改动检查 1. 是否有明显的逻辑错误 2. 是否有安全风险 3. 命名是否规范 4. 是否需要补充测试之后在对话里输/review就能触发。这个功能特别适合团队统一代码审查标准把规范写进命令文件谁用都一样。6.2 结合 Git 工作流Claude Code 能直接跑 Git 命令。你可以让它把当前改动提交commit message 用中文描述清楚改了什么它会自己git diff看改动生成合适的提交信息然后提交。推送前它还能帮你检查有没有漏掉的文件。配合分支使用更爽新建一个 feature/login 分支把登录相关的改动挪过去这种操作纯手动要敲好几条命令交给它一句话搞定。6.3 多项目与配置隔离如果你同时维护多个项目每个项目的CLAUDE.md是独立的互不干扰。全局配置在用户目录下的.claude/里可以放通用的偏好设置。API Key 建议用环境变量不要写死在项目里避免误提交。VSCode 里可以开多个窗口每个窗口对应一个项目Claude 面板各自独立。我一般一个窗口一个项目切换用CtrlR最近打开列表效率比来回 cd 高。6.4 性能与资源占用Claude Code 本身是个 Node 进程内存占用不大但如果你同时开多个实例加上 VSCode、浏览器8G 内存的机器会有点吃力。建议关掉不用的 VSCode 窗口或者用claude的会话管理功能一个实例处理多个任务。C 盘空间紧张的话注意 npm 全局包和缓存都默认在 C 盘。可以定期npm cache clean --force清理或者把 npm 缓存目录改到其他盘npm config set cache D:\npm-cache这个跟 Win11 C 盘清理是一个道理开发工具用久了缓存能占好几个 G。7. 从零到跑通的完整时间线把整个流程串一遍给你一个心理预期。第一步装 Node.js下载加安装大概五分钟验证两分钟。第二步装 Git五分钟配置三分钟。第三步装 Claude Codenpm 拉包看网速快的话一分钟慢的话十分钟。第四步登录配置三分钟。第五步装 VSCode 和扩展十分钟。第六步跑通第一个任务五分钟。顺利的话四十分钟内搞定卡壳主要卡在网络和 PATH 配置上。我的建议是装之前先把 npm 源换好PATH 问题提前检查能省不少时间。如果你之前重装过系统或者迁移过 SSD环境变量可能丢重新配一遍就行。最后分享一个我自己的习惯每配好一个新环境就把关键版本号记在备忘录里比如 Node 20.11、Git 2.43、Claude Code 1.x。下次出问题先对版本能快速定位是不是版本不匹配导致的。这个习惯帮我省了很多排查时间你也可以试试。