★ FEATURED ARTICLE 1. 先梳理思路Win11 下跑 Claude Code到底该怎么搭最近把主力开发机换成了 Windows 11IDEA 照常用但平时依赖的 Claude Code 在 Windows 上没法像在 Linux/macOS 那样直接跑。折腾了整整一天试过各种办法最后确定了一套最稳的组合WSL2 里装 Claude Code然后在 IntelliJ IDEA 的 Terminal 窗口里直接调用。这篇文章就记录这次完整过程包括踩过的坑、最终能直接抄的配置方案以及我实际用了两周之后沉淀下来的一些使用习惯。如果你也是 Windows 11 IDEA 用户想把 Claude Code 用起来按这篇的顺序操作基本不会卡壳。先说结论这套方案的完整链路是Windows 11 启用 WSL2在 WSL 的 Ubuntu 里装 Node.js通过 npm 安装 Claude Code然后把 IDEA 的 Terminal 默认 shell 指向 wsl.exe这样就等于把 Claude Code 完整接入了 IDEA。整个过程不破坏 Windows 本机环境也不影响 IDEA 现有的任何配置更不会污染系统 PATH。为什么绕这一圈而不是用其他方式下面详细聊。1.1 为什么不直接装 Windows 原生版本Claude Code 官方定位是命令行编程助手目前对 Linux 和 macOS 的支持最完整并没有发布独立的 Windows 原生安装包。网上确实有一些社区封装方案比如在 Windows 侧直接跑 cli 的包装层但我实测下来存在不少问题依赖转发不完整、路径转换容易出错、部分文件读写权限处理得很奇怪遇到问题排查成本反而更高。我的建议很简单既然官方环境是 Linux那就老老实实提供一个 Linux 运行环境。WSL2 不是传统意义的虚拟机它由 Windows 11 原生集成启动快、内存占用可控并且和 Windows 文件系统互相可访问。对我这种日常开发场景来说它就是一个跑在 Windows 里的轻量 Linux用来承载 Claude Code 再合适不过。1.2 为什么选择在 IDEA 终端里集成而不是单独开一个窗口可能有人会说既然 Claude Code 是命令行工具那我单独开一个 Windows Terminal 窗口操作不就行了说实话两种方式都能用但我坚持集成到 IDEA 终端里有三个实际原因。第一工作流不中断。我写代码的时候大多数时间都在 IDEA 里写一会儿代码切到终端让 Claude Code 改个文件、补个测试再切回编辑器看结果整个过程不需要离开 IDE比在多个窗口间来回切快得多。第二项目上下文路径天然正确。IDEA 打开某个项目后终端默认就停在当前项目根目录Claude Code 启动后会读取项目里的 CLAUDE.md、.claude 配置等文件能直接理解整个项目结构这是它比零散聊代码片段强很多的地方。第三IDEA 终端支持分栏。可以左边开着代码编辑器右边开着 Terminal 跑 Claude Code边看代码边看 AI 操作体验比全屏终端舒服不少。2. 环境准备WSL2 和 Node.js 一个都不能少2.1 确认你的 Windows 11 版本并开启 WSL在动手之前先确认系统版本。按 Win R输入 winver回车就能看到版本号。Windows 11 从 21H2 开始就内置了 wsl --install 这个命令建议先把系统更新到最新版我当前用的版本号是 23H2整个安装流程非常顺畅。确认版本没问题后右键开始菜单选择“终端(管理员)”先执行下面的命令安装 WSLwsl --install这个命令会自动完成几件事启用“适用于 Linux 的 Windows 子系统”功能、启用“虚拟机平台”功能、下载并安装 WSL2 内核然后默认安装 Ubuntu 发行版。整个过程可能需要几分钟安装完成后系统会提示重启按要求重启即可。重启之后打开 PowerShell 或者终端用这条命令确认一下 WSL 状态wsl -l -v正常情况下会看到 Ubuntu 后面标注的版本是 2说明已经跑在 WSL2 上。如果你之前机器上装过 WSL1 的老版本发行版版本号会显示 1需要手动升级wsl --set-version Ubuntu 2这一步等它转换完成就好期间不要关闭终端窗口。升级完成后重新查看确认版本号变成 2 再继续下一步。这里有一个很容易被忽略的点如果电脑上没有开启 BIOS 层面的虚拟化支持wsl --install 虽然能执行但后续启动 Ubuntu 会报错。遇到这种情况需要进 BIOS 打开 Intel VT-x 或者 AMD SVM 相关的选项。不过 2020 年以后的主流电脑基本都默认开启老机器要多留意一下。2.2 在 Ubuntu 里安装 Node.js 和 npmWSL 装好之后从开始菜单找到 Ubuntu 图标打开第一次启动会让你设置 Linux 用户名和密码。这个用户名和 Windows 用户名可以不一样密码在 Linux 里输入时不会显示字符这是正常的别以为是键盘失灵。接下来安装 Node.js。这里我强烈建议用 nvm 管理 Node 版本而不是直接 apt install nodejs。原因很简单Ubuntu 软件源里的 Node 版本通常偏老而 Claude Code 对 Node 版本有明确要求太老的版本跑不起来。nvm 不仅能让安装指定版本后面想切换版本也方便。先更新软件源并安装 nvm 的依赖sudo apt update sudo apt install curl -y然后安装 nvm注意版本号尽量用最新的我到写这篇文章时用的是 v0.39.7curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后nvm 会自动往 ~/.bashrc 里写入环境变量脚本。重新加载一下source ~/.bashrc确认 nvm 装好了执行 nvm --version 能看到版本号。接着安装 Node.js LTS 版本nvm install --lts nvm use --lts验证一下node -v npm -v我装的时候 Node 版本是 22.xnpm 是 10.xClaude Code 跑起来没有问题。这里多说一句有的教程会推荐直接去 Node 官网下载 Windows 安装包但那样装的是 Windows 版 Node和 WSL 里的 Linux 环境是两回事。我们是要在 Linux 环境里跑 Claude Code所以必须在 Ubuntu 内部装 Linux 版 Node。2.3 准备 Anthropic API KeyClaude Code 正常使用需要 Anthropic 官方 API Key。登录 Anthropic Console在 API Keys 页面创建一个新 Key创建成功后记得马上复制保存因为这个 Key 只会完整显示一次关掉页面就再也看不到了。拿到 Key 之后在 Ubuntu 终端里临时设置环境变量export ANTHROPIC_API_KEYsk-ant-你的key不过这样设置只在当前终端会话有效关掉窗口就没了。为了方便我建议写进 ~/.bashrcecho export ANTHROPIC_API_KEYsk-ant-你的key ~/.bashrc source ~/.bashrc验证一下echo $ANTHROPIC_API_KEY能打印出 Key 就说明配置成功。这里有一个安全提示千万不要把 API Key 直接提交到 Git 仓库里尤其是公开仓库一旦泄露就可能被恶意盗刷。如果项目里需要配置可以用 .env 文件并在 .gitignore 里忽略它。3. 安装 Claude Code 并在 IDEA 终端里激活3.1 通过 npm 安装 Claude Code环境变量配好之后安装 Claude Code 本身非常简单就一条命令npm install -g anthropic-ai/claude-code等待安装完成验证一下版本claude --version如果执行 claude 提示 command not found大概率是 npm 全局安装目录不在 PATH 里。先查看 npm 的全局 bin 路径npm prefix -g比如我这边输出的是 /home/用户名/.nvm/versions/node/v22.11.0那么全局可执行文件都在这个目录下。确认 PATH 里有没有它echo $PATH如果没有打开 ~/.bashrc 添加export PATH$PATH:/home/用户名/.nvm/versions/node/v22.11.0/bin然后 source ~/.bashrc 重新加载再执行 claude --version 就能通过了。3.2 把 IDEA 的 Terminal 默认 shell 指向 WSL环境全部就绪后现在轮到 IDEA 出场。打开你的 IntelliJ IDEA进入 File - SettingsWindows 下 Ctrl Alt S在左侧找到 Tools - Terminal。这里需要修改两个关键配置。第一个是 Shell path把它从默认的 PowerShell 改成指向 WSL我建议直接填wsl.exe注意不要画蛇添足写成 wsl.exe --distribution Ubuntu 之类的IDEA 默认会用启动 shell 时的用户名进入发行版直接写 wsl.exe 最干净。第二个是 Start directory可以留空让它默认使用当前项目目录。想要项目目录固定的话也可以手动指定比如\\wsl$\Ubuntu\home\你的用户名\项目目录改完配置点 Apply 保存。然后点 IDEA 底部工具栏的 Terminal 标签页如果终端打开后显示的是 Linux 风格提示符说明已经成功进入 WSL 环境。可以在终端里敲一句确认uname -a输出 Linux ... 就对了。这里补充一个不同 IDEA 版本的差异。新版本2023.x 和 2024.x的 Terminal 设置界面基本一致Shell path 直接填 wsl.exe 即可。如果你用的是社区版设置路径和操作方式也完全一样这是 IDEA 内置功能不需要额外装插件。3.3 首次登录 Claude Code 并初始化项目现在在 IDEA 终端里输入 claude回车Claude Code 的交互界面就会启动。首次运行如果有新版本更新提示一般会自动下载安装等待一下即可。登录阶段Claude Code 会检查 ANTHROPIC_API_KEY 环境变量是否存在如果存在就直接用没有的话会提示你去浏览器完成授权或者手动粘贴 Key。因为我们前面已经把环境变量写进 ~/.bashrc在 IDEA 终端里直接就能识别到一般不会卡在这一步。进入交互界面后可以先用 /status 查看当前登录账号和模型状态确认一切正常。接着是 Claude Code 一个非常重要的功能项目记忆。在项目根目录下执行claude然后在交互框里输入 /initClaude Code 会扫描当前项目结构自动生成一份 CLAUDE.md 文件。这个文件相当于是给 AI 看的项目说明书里面包含项目的构建命令、测试命令、代码风格约定等信息。生成之后后续每次在这个项目里启动 Claude Code它都会自动读取这份文件回答问题时能结合项目背景来操作效果比干聊代码片段强非常多。如果你有自己的规范比如团队代码规范、接口调用约定也可以手工编辑 CLAUDE.md 补充进去AI 都会遵守。3.4 配置自定义技能和模型参数如果你用的是新版 Claude Code可以充分利用 skills 功能。在项目根目录创建 .claude/skills 目录里面按规范放自己的 skill 定义文件就能让 Claude Code 掌握项目专属能力。比如我维护的一个前端项目里我写了一个 codereview skill让它用固定的视角检查代码先看类型定义是否完整再看有没有硬编码的魔法数字最后检查错误处理是否覆盖到边界场景。这样每次让它执行代码评审时输出内容非常稳定不会跑偏。另外如果默认模型不满足需求可以在启动时指定claude --model claude-sonnet-4-5还有 --permission-mode 参数可以控制权限模式比如用 acceptEdits 直接接受编辑或者用 plan 模式只做分析不落盘修改。我平时担心 AI 改坏代码一般会让它先输出方案确认没问题再让它改动所以会常用计划模式。4. 日常使用中的配置习惯与效率技巧4.1 项目路径映射怎么处理最舒服这是整个方案里我踩坑最深的地方。WSL 和 Windows 有一个双向的文件系统互通机制Windows 的系统盘挂载在 WSL 的 /mnt/c 下WSL 的内部文件也可以通过 \wsl$ 路径从 Windows 访问。问题就出在这如果项目放在 Windows 的 C:\Users\xxx\project那么在 WSL 里的真实路径是 /mnt/c/Users/xxx/project。Claude Code 在这个路径下工作确实可以但跨文件系统的文件读写非常慢尤其是 node_modules 庞大的前端项目每次扫描文件目录都让我等到怀疑人生。我的解决办法是新建项目时直接用 IDEA 打开 WSL 内部路径。在 IDEA 的 Open 窗口里地址栏输入 \wsl$\Ubuntu\home\你的用户名\workspace直接进入 Linux 文件系统然后把项目创建在这里。这样在 IDEA 终端里看到的就是 /home/你的用户名/workspace/项目名所有读写都在 Linux 文件系统内部完成速度完全不是一个量级。而且 IDEA 对 WSL 路径的索引支持很完善代码提示、跳转、调试这些功能都不受影响。如果你已经有很多项目在 Windows 盘符下也别急着迁移小项目影响不大。但确实发现 Claude Code 扫描代码库时明显卡顿迁移到 WSL 内部路径是治本的办法。4.2 给常用命令加别名减少重复输入每天在终端里和 Claude Code 打交道手速会越来越快但一些组合命令还是建议加个别名省点力气。打开 ~/.bashrc在末尾加几行alias clclaude alias clsclaude --continuecl 是启动 Claude Codecls 是继续上一次对话。这个继续功能很实用Claude Code 会把每次会话都存在本地你关掉终端再打开输入 cls 能接着之前的话题聊不用重新解释上下文。如果你追求更少的交互成本还可以加一句配置让 Claude Code 默认使用 plan 模式alias clplanclaude --permission-mode plan但我不建议把 plan 模式直接设成默认因为有些简单改动比如改个注释、格式化代码直接让它执行比反复确认要快得多。按需切换才最顺手。4.3 定期维护 CLAUDE.md让 AI 越用越懂项目CLAUDE.md 不能只是初始化时生成一次后面就一直不管。我的习惯是每完成一个阶段性功能就把相关的目录结构变化、新增的脚本命令同步进去。比如项目里加了 eslint 配置我会在 CLAUDE.md 里写清楚“代码格式检查使用 npm run lint规则基于 .eslintrc”。这样做的收益是积累性的。Claude Code 每次对话都会以 CLAUDE.md 作为基础上下文文件里描述得越准确AI 的初始判断就越靠谱生成的代码风格和项目现有代码越一致。说实话我用了两三周之后它已经能精准地按我项目的习惯命名变量、组织函数几乎不用事后调整格式。5. 常见问题与排查技巧实录这套方案我实际用下来遇到过的问题基本集中在几个方面整理成一个速查表遇到类似情况直接对照排查。问题现象根本原因解决方案claude: command not foundnpm 全局目录不在 PATH执行 npm prefix -g把输出目录追加到 ~/.bashrc 的 PATHIDEA 终端打开后显示 Windows 路径Shell path 没有生效重新检查 Settings - Tools - Terminal确认 Shell path 是 wsl.exeWSL 命令提示没有默认发行版安装了多个发行版但没指定默认wsl --set-default UbuntuAPI Key 配置了但 claude 不识别环境变量没有 source 到当前会话source ~/.bashrc再用 echo $ANTHROPIC_API_KEY 验证在 /mnt/c 项目里运行特别慢跨文件系统读写项目迁移到 \wsl$\Ubuntu\home\ 内部路径claude 更新失败或提示权限不足npm 全局目录归属问题不要用 sudo npm 安装改用 nvm 管理 Node 后重装出现 529 或请求被拒绝API Key 权限或额度问题检查 Key 是否有效、账户余额是否充足、模型名是否准确5.1 npm 全局安装后找不到命令的根因这个坑十个人里有九个会踩。用 npm install -g 安装后执行 claude 提示找不到多数情况不是因为没装上而是 npm 的全局 bin 目录没有在 shell 的 PATH 环境变量里。用 nvm 安装的 Node全局目录默认在 ~/.nvm/versions/node/版本号/bin这个目录不一定自动进来了。排查步骤很简单先 npm prefix -g 看输出再 echo $PATH 看有没有包含它。没有就按前面 3.1 的方式追加到 ~/.bashrc。有个细节追加完 source ~/.bashrc 之后如果你当前是在 IDEA 终端里最好重新打开一次终端页签确保环境变量真正生效因为每个终端会话只会在启动时加载一次配置。5.2 IDEA 终端进入 WSL 后提示找不到发行版如果你电脑上曾经装过其他 Linux 发行版比如 Debian、Kali又装了 UbuntuIDEA 终端启动 wsl.exe 时可能不知道用哪个发行版终端里会直接显示错误提示。解决办法是在 PowerShell 里执行wsl --set-default Ubuntu把 Ubuntu 设为默认发行版之后无论从哪个入口启动 WSL都会自动进入 Ubuntu。做完这一步记得重启一下 IDEA 终端。5.3 大项目扫描慢先查文件系统位置Claude Code 启动时会扫描项目目录读取 .git 信息和相关配置文件。如果项目在 /mnt/c 下这个扫描过程会明显慢。我有个后端项目代码量不算特别大但 vendor 目录里文件特别多在 /mnt/c 下启动 Claude Code 要等十几秒迁移到 WSL 内部路径后缩短到两三秒。建议你在项目根目录执行 pwd看看当前路径前缀是 /home 还是 /mnt/c。如果是后者我强烈建议把项目迁过去。IDEA 里直接拖项目文件到 WSL 路径也可以用但要留意 .idea 目录里的路径信息可能需要重新生成最简单的方式是用 IDEA 的 VCS 从 Git 重新 clone 一份到 WSL 路径下。5.4 关于 API Key 使用的一些实际操作心得最后说一点我对 API Key 管理的经验。除了把 Key 写进 ~/.bashrc还有两个进阶用法。如果你的工作流涉及多个项目并且不同项目想用不同账号的 Key可以在项目根目录建一个 .env 文件Claude Code 本身支持读取本地 .env 配置。这样每个项目可以绑定独立的额度方便分开统计。另外如果你有比较严格的流出安全要求可以考虑在 Anthropic Console 里给 Key 设置用量上限超出后会自动熔断防止意外消耗。这个功能对个人开发者可能用不上但对团队共享开发机的情况很有价值。6. 给新手的最后建议整套方案跑通之后我觉得最值得保留的习惯是让 Claude Code 成为项目里真正的协作者而不只是问答工具。每次进入一个新项目先花五分钟运行 /init 生成 CLAUDE.md把项目的技术栈、目录结构、常用命令写清楚。之后你的每一次提问、每一次让它改代码都在帮它积累对这个项目的理解。用久了你会明显感觉到它的输出质量在提高对代码库的把握越来越准确。最后再分享一个小技巧IDEA 的 Terminal 支持多标签页你可以开一个标签页专门跑 Claude Code另一个标签页跑 git 命令和构建脚本两个标签页互不干扰。配合 IDEA 的 Split Right 功能编辑器和终端左右分屏左边看代码右边和 Claude 对话这个布局我用了很久工作效率确实比来回切窗口高很多。希望这篇记录能帮你少走一些弯路把 Claude Code 顺利跑起来。
阅读完成 · 觉得有帮助？
