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:$PATH"Windows 上一般不需要手动加，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:NAME="value"，如果直接复制命令，很容易踩语法坑。
我个人建议：Windows 上长期使用还是 WSL。虽然前期多花半小时配置，但后面跑命令、装依赖、调权限都舒服太多，遇到问题也好搜，因为大量教程都是以 Ubuntu 环境写的。
3. 编辑器里的 Claude Code：VSCode、桌面版与 IDEA
装好命令行只是开始，大多数人真正天天面对的是编辑器。Claude Code 在编辑器里怎么集成，决定了你会不会真的频繁用它。
3.1 VSCode 集成终端的最短配置路径
VSCode 是目前社区里和 Claude Code 搭配最顺手的编辑器。不需要额外装官方插件，直接打开集成终端调用claude就行。
不过有几个配置我建议提前改掉，不然体验会打折扣：
- 在 VSCode 设置里把默认终端设置为 Git Bash（Windows）或 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_URL="https://api.deepseek.com/anthropic" export ANTHROPIC_AUTH_TOKEN="你的DeepSeek API Key"Windows PowerShell 对应写法是：
$env:ANTHROPIC_BASE_URL="https://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_1H=1的作用，是让 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/下。假设你要安装一个写测试用例的 skill：
mkdir -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 --registry=https://registry.npmmirror.com如果文件下载下来了，但运行时提示某个依赖缺失，重新执行npm install -g @anthropic-ai/claude-code或者手动安装对应依赖即可。还有一个小经验：升级 Claude Code 前最好看看版本变化，某些大版本升级后会改变配置文件的默认路径，旧配置可能失效。
6.2 API Error 400：context length 超限
这个报错我已经在不同后端里见过好多次。出错信息会提到类似this model's maximum context length is 10485 tokens，意思是当前模型窗口装不下了。
解决办法分几个层次：
- 如果是官方 Claude 模型，检查是不是意外设置了很小的上下文窗口参数。
- 如果是 DeepSeek 等第三方模型，看看该模型支持的最大上下文是多少，有时默认就是 32K 或 64K。
- 最有效的办法是开启新会话，或者使用
/compact命令压缩历史消息。 - 避免在同一个会话里粘贴超长代码片段，可以把代码拆成小文件让 AI 分段阅读。
我见过有人为了省 token 反复清除历史，结果 AI 忘了之前讨论的上下文，反而需要重新解释，效率更低。适度清理，而不是清得干干净净。
6.3 会话挂了几小时再恢复，花费突然大涨
这个和缓存机制直接相关。enable_prompt_caching_1h=1只缓存一小时，超过时间再恢复会话，所有历史消息都会被重新处理。解决办法很简单：长时间离开前，用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 真正用起来。
