Claude Code 多环境配置完全指南：Windows、Ubuntu、VSCode、IDEA 实用经验

Claude Code 最近是真的火。做后端的朋友在聊写前端的也在聊连搞嵌入式的都跑来问我能不能在 STM32 工程里用。火的原因其实很简单它把大模型从“聊天窗口”里拽出来直接按到终端里让 AI 能真正读代码、改代码、跑命令。但正因为大家都在不同机器、不同编辑器、不同模型后端里用它“多环境运行”就成了绕不过去的坎。这篇文章把我自己在 Windows、Ubuntu、VSCode、IDEA 这些环境里折腾 Claude Code 的经验全部摊开讲该装的、该配的、该避的坑都会提到希望能帮你省掉那些本可以避免的弯路。1. 先搞明白多环境运行到底在折腾什么很多人第一次听到“多环境”会懵觉得 Claude Code 不就是个命令行工具吗装好就能跑哪里来的环境问题实际上环境这个词在这里至少有三层含义每一层都可能让你运行结果完全不一样。1.1 环境的三张“面孔”第一张面孔是操作系统环境。Claude Code 是一个面向终端的工具它在 Linux 和 macOS 上跑得很顺在 Windows 上则要区分是原生终端、Git Bash 还是 WSL。这三者的路径规则、环境变量继承方式、进程权限都不一样同一个命令在不同终端里可能一个通一个报错。第二张面孔是编辑器环境。虽然 Claude Code 本质上是 CLI 工具但绝大多数人不会单独开一个黑框框用而是更习惯在 VSCode 的集成终端里调用或者通过桌面版、IDEA 插件等图形界面操作。这时候终端内的 shell 初始化文件、插件状态、工作区路径都会影响 Claude Code 的启动速度和能看到哪些文件。第三张面孔是模型后端环境。Claude Code 默认走 Anthropic 官方 API但社区里大量玩法是通过环境变量把请求转到 DeepSeek、Kimi 等第三方模型上。这相当于给同一个前端工具换了一个大脑而不同大脑的上下文窗口、推理速度、计费规则都不一样。1.2 谁需要多环境运行如果你只是在自己电脑上写写脚本那环境问题确实不痛不痒。但一旦出现下面这些场景就必须把三张面孔都理顺公司配的 Windows 笔记本个人电脑是 Ubuntu家里还有一台 Mac三台机器都要用 Claude Code。开发环境固定在 VSCode但临时要处理一个在 IDEA 里的 Java 老项目希望复用同一套配置。手上没有 Anthropic 官方 API 额度想把请求转到 DeepSeek 或其他兼容端点省成本。同时维护多个 Git 仓库希望每个仓库有独立会话和上下文不互相污染。这些情况我都实际遇到过。一开始也偷懒每换一个环境就重新查一遍安装教程结果发现每次踩的坑都不一样。后来花了一个周末把整个流程梳理清楚后面再切环境就非常顺了。下面这套方法是目前我实测下来最省心的组合。2. 跨平台安装第一次把 Claude Code 跑起来不管最终在哪个环境运行第一步都是安装。Claude Code 的官方推荐方式是 npm 全局安装所以需要先准备好 Node.js 环境。这一步看似基础但恰恰是最多人卡住的地方。2.1 先装 Node.js 和 npm别用旧版本Claude Code 对 Node.js 版本有要求官方建议使用 18 以上的 LTS 版本。我最早在 Ubuntu 上用系统自带的 apt 装 Node.js结果版本停留在 16安装后运行直接报语法错误。后来老老实实从 NodeSource 或者 nvm 装版本。比较推荐的是用 nvm 管理 Node.js这样一台机器上可以同时存在多个版本切换项目时不会被全局环境绑死。安装命令在不同系统上略有差异# Ubuntu / macOS curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20 # Windows 则可以直接下载 nvm-windows 安装包 # 或者偷懒装一个最新 LTS 的 Node.js 安装包省心。装完之后在终端里确认版本node -v npm -v这里有个小细节Windows 用户安装 Node.js 时安装向导里有个 “Add to PATH” 选项必须勾上否则后面在 PowerShell 里敲 npm 会提示“无法识别”。装完后最好重新打开一次终端让 PATH 生效。2.2 用 npm 全局安装并验证Node.js 就绪之后Claude Code 的安装其实只有一条命令npm install -g anthropic-ai/claude-code安装过程可能会遇到 npm 网络慢的问题可以临时换用国内镜像源具体命令我放在后面报错章节。安装完成后运行claude --version如果输出版本号说明核心安装成功。第一次运行claude时它会要求登录或设置 API Key按提示操作即可。需要注意npm 全局安装目录有时候不在 PATH 里。Linux 和 macOS 上如果提示claude: command not found可以检查npm prefix -g然后把对应的 bin 目录加到.bashrc或.zshrc中export PATH$(npm prefix -g)/bin:$PATHWindows 上一般不需要手动加npm 会自动把全局目录放到用户 PATH 中。2.3 Windows 用户原生终端还是 WSL这是 Windows 环境里最大的分歧点。Claude Code 官方文档早期对 Windows 的支持并不算好很多能力比如复杂 shell 命令、文件权限处理在 PowerShell 里会碰到兼容问题。社区里比较常见的做法是安装 WSL在 Ubuntu 子系统里跑 Claude Code然后用 VSCode 的 Remote-WSL 插件连接。这个组合我用下来最稳文件读写和命令执行都更接近 Linux 原生体验。当然如果你只是临时处理小任务在 Git Bash 里跑也可以。Git Bash 对 Unix 命令兼容不错npm 和 claude 都能正常调用。但要注意Git Bash 里设置环境变量的语法是export而 PowerShell 里是$env:NAMEvalue如果直接复制命令很容易踩语法坑。我个人建议Windows 上长期使用还是 WSL。虽然前期多花半小时配置但后面跑命令、装依赖、调权限都舒服太多遇到问题也好搜因为大量教程都是以 Ubuntu 环境写的。3. 编辑器里的 Claude CodeVSCode、桌面版与 IDEA装好命令行只是开始大多数人真正天天面对的是编辑器。Claude Code 在编辑器里怎么集成决定了你会不会真的频繁用它。3.1 VSCode 集成终端的最短配置路径VSCode 是目前社区里和 Claude Code 搭配最顺手的编辑器。不需要额外装官方插件直接打开集成终端调用claude就行。不过有几个配置我建议提前改掉不然体验会打折扣在 VSCode 设置里把默认终端设置为 Git BashWindows或 WSL而不是 PowerShell避免命令兼容问题。如果使用 WSL记得用 Remote-WSL 打开项目目录否则终端里的路径还是 Windows 路径Claude Code 在读取文件时会姿势不对。建议把claude的启动命令绑定到一个快捷键或任务方便随时唤起。我自己的办法是创建.vscode/tasks.json配置一个终端任务一键启动。一个常见的坑是VSCode 集成终端里启动 Claude Code 后如果整个窗口被关闭会话也就没了。如果项目比较复杂建议用claude --continue或者claude -c恢复最近会话而不是重新开一个新上下文。3.2 Claude Code Desktop 桌面版值得装吗热词里很多人搜“Claude Code Desktop 国内下载”说明大家更习惯图形界面。桌面版本质上还是包了一层壳核心执行逻辑没有变化但提供了更直观的聊天式窗口和文件视图。如果你主要是聊天式操作、不太依赖编辑器里的文件树桌面版可以装。从官方渠道下载安装包网络通畅时能正常下载安装。首次启动同样要完成登录验证之后会默认打开一个会话窗口。不过说实话我日常还是 VSCode 集成终端用得更多。桌面版在单文件修改场景下体验不错真要到大型项目里跨文件重构还是编辑器原生环境更顺手。3.3 在 JetBrains IDEA 里接入的思路用 Java 或 Kotlin 的朋友通常会问IDEA 里能不能用 Claude Code。IDEA 官方插件市场里有不少封装层插件但质量参差不齐。我的做法比较保守在项目目录下直接启用终端里的claude配合 IDEA 自带的终端面板效果其实不差。关键区别是 IDEA 终端默认用的可能是 cmd 或 PowerShell在 Windows 下要手动切换成 Git Bash。另外IDEA 里打开的项目根目录路径有时会带着中文或空格Claude Code 对路径敏感建议把项目放到纯英文路径下省去不少麻烦。如果你坚持要装插件先在插件市场搜索 Claude Code 相关插件看下载量和更新时间尽量选最近三个月内更新过的。不要一上来就装太多插件之间给 Claude Code 注入的环境变量可能会冲突反而导致 API 请求异常。4. 模型后端多环境从官方 API 到 DeepSeek 等第三方模型Claude Code 本身是一个“客户端”默认只认 Anthropic API。但很多人没有官方 Key或者觉得价格吃不消转而把请求转到 DeepSeek 等模型上。这套玩法能不能跑通其实就看环境变量设置得对不对。4.1 环境变量切换背后的原理Claude Code 在启动时读取一组环境变量其中包括ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。前者决定了请求发到哪个服务器后者决定鉴权信息。Claude Code 内部按 Anthropic 的 API 协议构造请求只要你指向的模型后端也兼容这套协议理论上就能切换。这就是“接入 DeepSeek”这类教程的核心逻辑。DeepSeek 提供了 Anthropic 兼容的接口地址所以只要把ANTHROPIC_BASE_URL指向它鉴权 Token 换成 DeepSeek 的 Key即可完成切换。官方 API 模型名则是通过模型选择或参数传入。这种做法的优点是灵活缺点是很依赖“兼容”这两个字。兼容并不意味着所有功能都一致。比如工具调用、文件读写、长上下文这些高阶特性第三方模型不一定都支持实际使用中会频繁遇到半路报错。4.2 实操把 Claude Code 接到 DeepSeek以 Ubuntu 环境为例可以在.bashrc或当前终端会话中设置环境变量export ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic export ANTHROPIC_AUTH_TOKEN你的DeepSeek API KeyWindows PowerShell 对应写法是$env:ANTHROPIC_BASE_URLhttps://api.deepseek.com/anthropic $env:ANTHROPIC_AUTH_TOKEN你的DeepSeek API Key设置完成后启动claude在会话中把模型切换到对应的 DeepSeek 模型名称。这里有个容易踩的坑模型名称写错会报 404 或 400 错误。DeepSeek 的 Anthropic 兼容接口通常对应的是deepseek-chat或deepseek-reasoner具体以官方文档为准。另外环境变量只是当前终端进程生效关掉终端再开就没了。如果你希望长期使用第三方模型就把 export 写到 shell 配置文件里Windows 用户可以用setx设置用户环境变量。我个人不推荐在全局配置里写死因为一旦要切回官方 API还得重新删变量不如在项目目录里放一个set_env.sh脚本按需 source。4.3 1M 上下文窗口大项目到底怎么用热词里“Claude Code 1M 上下文”指的就是把上下文窗口扩展到百万 token 级别。官方的 1M 上下文能力确实存在但并不是无脑开启就万事大吉。上下文窗口越大模型需要处理的 token 越多响应时间和成本都会同步上涨。我自己的体会是1M 上下文更适合“整个代码库级别的问答和重构”而不是日常小修小补。例如手头有一个中型 monorepo想让它全局搜索所有 API 调用点并给出重构建议这种场景用大窗口就很爽。但要是一次会话连续塞几十个文件输出质量反而会下降。如果遇到模型提示 context length 超限很多人的第一反应是 “换更大的上下文窗口”但更务实的做法是清掉不再需要的旧消息把任务拆成多个子会话。上下文窗口是资源不是给你当移动硬盘用的。4.4 缓存配置 enable_prompt_caching_1h 到底有没有用这可能是最近群里聊得最多的一个配置。export ENABLE_PROMPT_CACHING_1H1的作用是让 Claude Code 尝试复用一小时窗口内的上下文缓存从而降低重复 token 的计费。我的实测结论是如果你在“同一个会话内”频繁进行多轮修改它能明显减少重复处理系统提示和工具定义的开销费用确实会降一些。但如果你每次都是新开会话、或者隔了几个小时再回来那缓存早已失效效果几乎可以忽略。这里还可以解释一个现象为什么一个会话等待几个小时之后恢复会话时会耗费大涨因为缓存过期后Claude Code 需要把系统提示、历史消息、工具定义全部重新处理一遍这时候的费用自然抬升。所以长时间隔断的会话建议直接开新上下文不要硬续。5. 项目级多环境多会话、大型代码库与 Skills 的落地除了系统和模型多环境还体现在“项目”这个层面。不同 Git 仓库、不同技术栈、不同目录结构都应该有独立且清晰的管理方式。这里分享我一直在用的几个方法。5.1 多目录多会话并行避免互相污染Claude Code 的工作目录会直接影响它能看到哪些文件。如果在根目录运行claude它会把整个仓库的内容都纳入上下文如果是大型 monorepo信息量会爆炸跑起来又慢又贵。我的做法是在多个终端窗口分别进入不同子模块目录各自启动独立会话。比如前端项目在apps/web后端在services/api就分别开两个终端。Claude Code 在各自目录里使用独立的会话记录互不干扰。这样还能利用多个 API 并发效率提升明显。如果你同时维护多个仓库建议为每个仓库设置独立的CLAUDE.md文件里面写清楚仓库的结构、构建命令、代码风格。Claude Code 会在启动时自动读取这个文件相当于给 AI 一份项目使用说明书比自己每次手动解释好太多。5.2 大型代码库里的三个习惯在大型代码库中运行 Claude Code 和在小项目里完全不同。我踩过不少坑之后总结出三个习惯第一善用忽略文件。Claude Code 支持类似.gitignore的忽略规则通过.claudeignore文件排除node_modules、构建产物、日志目录等无关内容能大幅降低上下文噪音和 token 消耗。第二不要一次性把整个目录拖进对话。很多人喜欢说“分析一下当前项目”结果 Claude Code 会扫描大量无关文件。应该缩小范围比如具体到某个模块、某个函数文件让它针对局部做分析。第三充分利用子目录启动。就算项目根目录有完整.claudeignore在子目录启动仍然是最快的方式因为路径筛选是第一道关卡。嵌入式 STM32 项目我一般就在Core/Src或Drivers下启动效果比在根目录好不少。5.3 手动安装 GitHub Skills热词里有人问“Claude Code 怎么手动装 GitHub 上的 skills”。如果只是从仓库克隆 skill 文件夹并不需要什么复杂操作。官方规范里skill 通常是一组 Markdown 文件和脚本只要放到指定目录就能被 Claude Code 识别。项目级 skill 放在当前目录的.claude/skills/下用户级 skill 放在~/.claude/skills/下。假设你要安装一个写测试用例的 skillmkdir -p .claude/skills git clone https://github.com/example/test-writing-skill .claude/skills/test-writing然后重新启动claude在会话里用 skill 名称触发即可。需要留意的是不同 skill 对 Claude Code 版本的适配程度不同如果触发后没反应先查看 skill 的 README确认是否需要额外安装 Python 依赖或 Node 脚本。6. 踩坑合集常见报错与排查思路前面聊了那么多“应该怎么做”最后这部分把我在实际使用中遇到的高频问题集中列出来方便当字典查。很多报错信息看着吓人其实背后原因都挺朴实。6.1 安装、下载与命令找不到最典型的报错就是claude: command not found。除了上一节提到的 PATH 问题还有可能是 npm 全局目录权限不对。Linux 上可以通过npm config get prefix查看如果目录需要sudo才能写建议用 nvm 安装 Node避免权限麻烦。npm 安装卡住也是高频问题就是网络下载不动。这种情况可以临时切换 npm 镜像npm install -g anthropic-ai/claude-code --registryhttps://registry.npmmirror.com如果文件下载下来了但运行时提示某个依赖缺失重新执行npm install -g anthropic-ai/claude-code或者手动安装对应依赖即可。还有一个小经验升级 Claude Code 前最好看看版本变化某些大版本升级后会改变配置文件的默认路径旧配置可能失效。6.2 API Error 400context length 超限这个报错我已经在不同后端里见过好多次。出错信息会提到类似this models maximum context length is 10485 tokens意思是当前模型窗口装不下了。解决办法分几个层次如果是官方 Claude 模型检查是不是意外设置了很小的上下文窗口参数。如果是 DeepSeek 等第三方模型看看该模型支持的最大上下文是多少有时默认就是 32K 或 64K。最有效的办法是开启新会话或者使用/compact命令压缩历史消息。避免在同一个会话里粘贴超长代码片段可以把代码拆成小文件让 AI 分段阅读。我见过有人为了省 token 反复清除历史结果 AI 忘了之前讨论的上下文反而需要重新解释效率更低。适度清理而不是清得干干净净。6.3 会话挂了几小时再恢复花费突然大涨这个和缓存机制直接相关。enable_prompt_caching_1h1只缓存一小时超过时间再恢复会话所有历史消息都会被重新处理。解决办法很简单长时间离开前用claude -c把当前状态记录到会话文件回来后开新会话并引用该会话的关键结论而不是命令式地恢复老会话。如果你确实需要完整保留上下文可以手动把重点内容写入CLAUDE.md让新会话在启动时自动读取避免重头开始。6.4 卸载与重装卸载 Claude Code 比想象中简单全局 npm 包卸载即可npm uninstall -g anthropic-ai/claude-code同时清理用户目录下的.claude文件夹保留的话里面可能包含旧版配置、skills 和会话记录有时候会影响重装后的行为。如果你只是想重置配置而不完全卸载可以只删除.claude.json或settings.json。重装时如果遇到旧版本残留最干净的方法是先卸载、再删除.claude目录、最后重新安装。别嫌麻烦很多诡异报错就是这么治好的。最后说点个人体会Claude Code 的环境配置真的不难难的是有没有耐心把每一步的原理搞清楚。我第一次在 Windows 上折腾时光是 WSL 和 PATH 就花了两个小时。但理顺之后再装第二台、第三台机器基本十分钟内就能搞定。希望这篇能让你少走点弯路不管是在 Ubuntu、Windows 还是 VSCode、IDEA 里都能把 Claude Code 真正用起来。