尧图网站建设 
1. 多环境运行的真实痛点为什么一个终端跑不通所有场景刚接触 Claude Code 的人十有八九会在某个时刻撞上同一堵墙在公司的开发机上配好了回家换自己的笔记本同样的命令敲下去要么提示找不到配置要么连不上模型要么干脆把项目里的文件改得乱七八糟。这不是你手笨而是 Claude Code 的运行逻辑天然就和“环境”两个字绑得很死。Claude Code 本质上是一个跑在终端里的智能体它会读取当前工作目录、读取环境变量、读取配置文件然后基于这些信息决定用哪个模型、走哪条网络通道、能访问哪些文件、执行哪些命令。换句话说它不是一个装完就一劳永逸的软件而是一个高度依赖上下文环境的工具。你在 A 环境里调好的那一套搬到 B 环境里大概率会水土不服。我见过太多人把时间浪费在反复重装、反复改全局配置上。今天在 Windows 上把 API Key 写进了系统环境变量明天在 Ubuntu 服务器上又得重新 export 一遍公司内网要求走特定的代理地址家里直连又不需要项目 A 要用某个模型项目 B 又得换另一个。如果每次都去动全局配置最后的结果就是全局配置变成一锅粥谁也说不清哪个变量是给哪个项目用的。所以“多环境运行”这件事核心不是让你学会几条命令而是让你建立一套环境隔离的思路。这套思路的目标很明确让同一个 Claude Code在不同的机器、不同的项目、不同的网络条件下都能用最少的改动跑起来而且互不干扰。下面我会从整体设计、核心细节、实操落地、问题排查四个层面把这件事讲透。2. 整体设计思路用分层配置替代全局硬编码2.1 为什么不能只靠系统环境变量很多人第一反应是“那我把所有配置都写进系统环境变量不就行了”。这个思路在单机单项目场景下确实能用但一旦环境变多就会崩。原因有三点。第一系统环境变量是全局的你在 Windows 上设了ANTHROPIC_API_KEY那这台机器上所有终端、所有项目都会读到它。如果公司项目和个人项目用的是不同的 Key就会互相覆盖你每次切换都得改系统设置极其低效。第二系统环境变量的修改往往需要重启终端甚至重启系统才能生效调试成本高。你在排查一个连接问题时改完变量发现没生效会误以为是配置写错了实际上是环境没刷新。第三不同操作系统对环境变量的处理方式不一样。Windows 用set和系统属性面板Linux 和 macOS 用export和 shell 配置文件语法和生效范围都有差异。把配置绑死在系统层等于把自己锁死在某一台机器上。2.2 分层配置的核心模型我更推荐的做法是把配置分成三层从外到内依次是系统层、用户层、项目层。每一层负责不同粒度的信息优先级从低到高。系统层放的是最通用的东西比如可执行文件的路径、基础的运行时依赖。这一层你基本不用为 Claude Code 单独做什么装好 Node 环境、确保claude命令能被找到就够了。用户层放的是你个人跨项目通用的偏好比如你习惯用的默认模型、你个人的 API Key。这一层通常写在用户主目录下的配置文件里比如~/.claude/settings.json或者 shell 的启动脚本里。项目层放的是这个项目专属的配置比如这个项目要用哪个模型、要不要开启某些实验性功能、工作目录的边界在哪里。这一层写在项目根目录下的.claude/settings.json里跟着代码仓库走换机器拉下来就能用。这样分层之后你换机器只需要保证系统层和用户层就位项目层的配置跟着仓库自动同步。换项目时项目层的配置会自动覆盖用户层的默认值不需要你手动切换。2.3 配置文件与环境变量的分工这里要澄清一个常见误区配置文件和环境变量不是二选一的关系而是各司其职。环境变量适合放敏感信息和机器相关的路径。比如 API Key你不应该把它写进项目配置文件然后提交到仓库里那等于把钥匙挂在门上。正确的做法是把 Key 放在环境变量里配置文件里只写引用。配置文件适合放结构化的偏好设置。比如你想指定默认模型、想设置某些功能的开关、想定义权限规则这些用 JSON 写比用一堆环境变量清晰得多也更容易版本管理。我一般的做法是项目里的.claude/settings.json写非敏感的配置敏感信息通过环境变量注入然后在文档里说明需要设置哪些环境变量。这样既保证了配置的可移植性又保证了安全性。3. 核心细节解析环境变量、settings.json 与 PathMux 的配合3.1 环境变量的设置位置与生效范围环境变量这东西设置的位置不同生效的范围和时机就完全不同。我把它分成四种常见位置你可以对照自己的场景选择。设置位置生效范围生效时机适用场景系统属性面板全系统重启终端或系统Windows 上长期使用的通用变量shell 启动脚本当前用户所有终端新开终端Linux/macOS 个人通用配置项目启动脚本当前项目执行脚本时项目专属变量随项目走命令行临时设置当前命令立即临时调试、一次性覆盖在 Linux 和 macOS 上如果你把export写进~/.bashrc或~/.zshrc那新开的每个终端都会带上这个变量。但要注意如果你用的是 zsh写进~/.bashrc是不生效的这是新手最常踩的坑之一。判断自己用的是哪个 shell敲echo $SHELL看一眼就行。在 Windows 上图形界面的系统属性面板设置的是持久变量但已经打开的终端不会自动刷新。你改完之后要么关掉重开要么在 PowerShell 里手动刷新一下环境。临时用的话PowerShell 里用$env:变量名值cmd 里用set 变量名值但这两个都只在当前窗口有效。3.2 settings.json 的层级与优先级Claude Code 的配置文件有多个可能的位置优先级从高到低大致是项目级配置、用户级配置、系统级默认。项目级的.claude/settings.json会覆盖用户级的~/.claude/settings.json。这个设计的好处是你可以在用户级配置里放一套通用的默认值然后在具体项目里只覆盖需要改的那几项。比如用户级配置里默认用某个模型项目 A 想换一个就只在项目 A 的配置文件里写模型这一项其他配置自动继承。配置文件的格式是 JSON写的时候要注意几点。第一JSON 不支持注释别想着在里面写//说明会解析失败。第二字符串要用双引号不能用单引号。第三最后一项后面不能有多余的逗号这是 JSON 解析报错的高频原因。一个典型的项目级配置大概长这样{ model: claude-sonnet-4-20250514, permissions: { allow: [Read, Write, Bash(git status)], deny: [Bash(rm -rf)] }, env: { PROJECT_ROOT: /home/user/projects/myapp } }这里的env字段可以让你在配置文件里定义环境变量这些变量会在 Claude Code 运行时注入。但再次强调敏感信息不要写在这里。3.3 PathMux 在多环境中的角色PathMux 这个词在 Claude Code 的语境里通常指的是对路径和命令的复用与切换机制。简单说它解决的是“同一个工具在不同环境下路径不一样”的问题。举个实际例子。你在本地开发时项目路径是/Users/you/project到了服务器上变成/var/www/project。如果配置里写死了绝对路径换环境就废了。PathMux 的思路是用变量或者相对路径来表达让同一份配置在不同机器上都能解析到正确的路径。在 Claude Code 里你可以通过环境变量来传递这些路径信息然后在配置里引用。比如在本地 shell 里设置PROJECT_ROOT指向本地路径在服务器上设置同一个变量指向服务器路径配置文件里统一用这个变量。这样配置文件本身不用改换环境只需要改环境变量。这个思路和很多构建工具处理路径的方式是一致的核心就是把变化的部分抽出来让不变的部分保持稳定。4. 实操过程从零搭建一套可切换的多环境配置4.1 基础环境准备与安装确认在动手配多环境之前先把基础环境确认一遍。Claude Code 依赖 Node.js 运行时所以第一步是确认 Node 装好了而且版本不能太老。node --version npm --version如果这两条命令能正常输出版本号说明基础环境没问题。如果提示找不到命令那就得先装 Node。Windows 用户去官网下载安装包Linux 用户可以用包管理器macOS 用户可以用 Homebrew。装完之后重新开一个终端再验证。接下来确认 Claude Code 本身能不能跑起来claude --version如果这条命令报错说明 Claude Code 没装好或者没在 PATH 里。安装方式通常是通过 npm 全局安装装完之后 npm 的全局 bin 目录需要在 PATH 里否则命令找不到。这是新手最常见的“装完了但用不了”的原因。4.2 用户级配置的建立基础环境就绪后先建立用户级配置。这个配置放在你的主目录下对所有项目生效。在 Linux 和 macOS 上我建议把通用的环境变量写进 shell 启动脚本。先确认自己用的是哪个 shellecho $SHELL如果是/bin/zsh就编辑~/.zshrc如果是/bin/bash就编辑~/.bashrc。在文件末尾加上export ANTHROPIC_API_KEY你的密钥 export CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514保存后执行source ~/.zshrc或source ~/.bashrc让配置立即生效或者直接新开一个终端。验证一下echo $ANTHROPIC_API_KEY能打印出你设置的值就说明生效了。在 Windows 上如果你用的是 PowerShell可以编辑 PowerShell 的 profile 文件路径通常是$PROFILE。在里面加上$env:ANTHROPIC_API_KEY你的密钥 $env:CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514保存后重启 PowerShell 即可。4.3 项目级配置的建立用户级配置搞定后进入具体项目目录建立项目级配置。在项目根目录下创建.claude文件夹里面放settings.json。mkdir -p .claude然后创建配置文件。这里的关键是只写这个项目需要覆盖的配置不要把所有东西都抄一遍。比如这个项目要用不同的模型就只写模型{ model: claude-opus-4-20250514 }如果这个项目需要特定的权限规则比如只允许读取不允许写入就加上权限配置。如果这个项目需要引用某个环境变量来定位路径就在env字段里定义。创建完之后建议把.claude/settings.json提交到版本控制这样团队其他人拉下来就能用同一套配置。但如果有敏感信息一定要用环境变量引用不要把明文写进去。4.4 多环境切换的实操演示现在假设你有两个环境本地开发机和远程服务器。本地用一套 Key服务器用另一套本地项目路径和服务器不一样本地想用快速模型服务器想用更强的模型。本地环境的用户级配置里设置本地 Key 和本地路径变量export ANTHROPIC_API_KEY本地密钥 export PROJECT_ROOT/Users/you/projects/myapp服务器环境的用户级配置里设置服务器 Key 和服务器路径export ANTHROPIC_API_KEY服务器密钥 export PROJECT_ROOT/var/www/myapp项目级配置文件里统一引用变量不写死路径{ model: claude-sonnet-4-20250514, env: { WORK_DIR: ${PROJECT_ROOT} } }这样同一份项目配置在本地和服务器上都能正确解析到各自的路径。切换环境时你不需要改项目里的任何文件只需要保证对应机器的用户级环境变量设置正确。如果临时想覆盖某个配置比如这次想用另一个模型直接在命令行里临时设置CLAUDE_DEFAULT_MODELclaude-opus-4-20250514 claude这条命令只在当前这次执行中生效不会影响其他终端和后续使用。5. 常见问题与排查技巧实录5.1 配置不生效的排查顺序配置改完发现没生效这是最高频的问题。我的排查顺序是这样的。第一步确认改的是哪个文件。很多人改了~/.bashrc但自己用的是 zsh那当然不生效。先echo $SHELL确认 shell 类型。第二步确认配置有没有被加载。用echo $变量名看变量是否存在。如果不存在说明启动脚本没被读取或者写错了位置。第三步确认配置文件的位置对不对。Claude Code 读的是项目根目录下的.claude/settings.json如果你在子目录里创建它是读不到的。确认当前工作目录是不是项目根目录。第四步确认 JSON 格式有没有错。JSON 对格式很严格多一个逗号、少一个引号都会导致整个文件解析失败。可以用在线的 JSON 校验工具检查一下或者用python -m json.tool settings.json验证。5.2 环境变量冲突与覆盖问题当同一个变量在多个地方被设置时到底哪个生效这取决于设置的时机和位置。一般来说后设置的覆盖先设置的。命令行临时设置优先级最高因为它是在执行命令的那一刻注入的。项目级配置里的env字段次之。用户级 shell 配置再次之。系统级最低。如果你发现某个变量的值和预期不符可以用env | grep 变量名看看当前终端里所有相关的变量确认是不是被别的地方覆盖了。在 Windows PowerShell 里用Get-ChildItem Env:列出所有环境变量。还有一种情况是变量名拼写不一致。比如你设置的是ANTHROPIC_API_KEY但程序读的是ANTHROPIC_KEY那自然读不到。这种问题只能靠仔细核对文档和配置来避免。5.3 跨平台路径问题的处理Windows 和 Linux 的路径分隔符不一样Windows 用反斜杠Linux 用正斜杠。如果你在配置里写死了路径跨平台时就会出问题。处理办法是尽量用相对路径或者用环境变量传递路径。如果必须写绝对路径在 Windows 上用正斜杠通常也能被识别但最稳妥的还是用变量。另外Windows 上路径里有空格是常见情况比如C:\Program Files\...。在命令行里引用这种路径时记得用引号包起来否则会被当成两个参数。5.4 常见问题速查表现象可能原因排查方法命令找不到PATH 未包含安装目录检查 npm 全局 bin 是否在 PATH配置不生效改错了 shell 配置文件确认 $SHELL 与编辑的文件一致JSON 解析失败格式错误多余逗号或引号用 json.tool 校验变量值为空变量名拼写错误或未加载echo 变量名确认换机器后路径错误配置里写死了绝对路径改用环境变量或相对路径模型不对项目配置未覆盖用户配置检查项目级 settings.json5.5 几个我踩过的坑第一个坑是以为改了配置文件就立即生效。实际上很多配置需要重启终端或者重新加载才会被读取。我一开始改完就测试发现没变化折腾半天才发现是没刷新。第二个坑是在项目配置文件里写了 API Key然后不小心提交到了仓库。虽然发现后立刻撤销了但这件事让我养成了敏感信息一律走环境变量的习惯。第三个坑是 Windows 上用了 PowerShell 的临时变量设置然后换了个 cmd 窗口发现变量没了。临时变量只在当前窗口有效跨窗口是不共享的这个一定要记住。第四个坑是 JSON 文件里写了注释导致解析失败。JSON 标准不支持注释任何注释都会导致解析错误。想写说明的话可以单独写一个 README 文件。6. 进阶技巧让多环境切换更顺滑6.1 用脚本封装环境切换如果你经常在多个环境之间切换可以写一个小脚本把切换动作封装起来。比如在项目根目录放一个env-local.sh和env-server.sh里面分别 export 对应的变量用的时候 source 一下就行。# env-local.sh export ANTHROPIC_API_KEY本地密钥 export PROJECT_ROOT/Users/you/projects/myapp export CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514# env-server.sh export ANTHROPIC_API_KEY服务器密钥 export PROJECT_ROOT/var/www/myapp export CLAUDE_DEFAULT_MODELclaude-opus-4-20250514用的时候source env-local.sh就切到本地配置source env-server.sh就切到服务器配置。这样比手动改系统环境变量快得多也不容易出错。6.2 配置文件的版本管理策略项目级的.claude/settings.json建议提交到仓库但要注意里面不能有敏感信息。用户级的配置不要提交因为那是你个人的偏好而且可能包含密钥。如果团队协作可以在仓库里放一个settings.example.json作为模板里面写清楚需要哪些配置项但不写具体值。新人拉下来之后复制一份改成自己的settings.json再填入自己的环境变量。6.3 多项目并行的隔离思路如果你同时维护多个项目每个项目都有自己的配置需求那项目级配置的隔离就很重要。核心原则是项目配置只写这个项目特有的东西通用的东西放用户级。比如所有项目都用同一个 API Key那就把 Key 放用户级环境变量项目配置里不写。项目 A 需要特殊权限规则就只在项目 A 的配置里写权限。项目 B 需要不同模型就只在项目 B 的配置里写模型。这样每个项目的配置文件都很短容易维护也不容易互相干扰。我在实际使用中发现把配置分层之后换机器和换项目的成本大幅下降。以前换一台机器要折腾半小时现在只要保证用户级环境变量设置好项目拉下来就能直接跑。这个思路不只适用于 Claude Code很多命令行工具的多环境管理都可以套用同样的逻辑。 Claude Code多环境配置实战：分层管理与环境隔离
1. 多环境运行的真实痛点为什么一个终端跑不通所有场景刚接触 Claude Code 的人十有八九会在某个时刻撞上同一堵墙在公司的开发机上配好了回家换自己的笔记本同样的命令敲下去要么提示找不到配置要么连不上模型要么干脆把项目里的文件改得乱七八糟。这不是你手笨而是 Claude Code 的运行逻辑天然就和“环境”两个字绑得很死。Claude Code 本质上是一个跑在终端里的智能体它会读取当前工作目录、读取环境变量、读取配置文件然后基于这些信息决定用哪个模型、走哪条网络通道、能访问哪些文件、执行哪些命令。换句话说它不是一个装完就一劳永逸的软件而是一个高度依赖上下文环境的工具。你在 A 环境里调好的那一套搬到 B 环境里大概率会水土不服。我见过太多人把时间浪费在反复重装、反复改全局配置上。今天在 Windows 上把 API Key 写进了系统环境变量明天在 Ubuntu 服务器上又得重新 export 一遍公司内网要求走特定的代理地址家里直连又不需要项目 A 要用某个模型项目 B 又得换另一个。如果每次都去动全局配置最后的结果就是全局配置变成一锅粥谁也说不清哪个变量是给哪个项目用的。所以“多环境运行”这件事核心不是让你学会几条命令而是让你建立一套环境隔离的思路。这套思路的目标很明确让同一个 Claude Code在不同的机器、不同的项目、不同的网络条件下都能用最少的改动跑起来而且互不干扰。下面我会从整体设计、核心细节、实操落地、问题排查四个层面把这件事讲透。2. 整体设计思路用分层配置替代全局硬编码2.1 为什么不能只靠系统环境变量很多人第一反应是“那我把所有配置都写进系统环境变量不就行了”。这个思路在单机单项目场景下确实能用但一旦环境变多就会崩。原因有三点。第一系统环境变量是全局的你在 Windows 上设了ANTHROPIC_API_KEY那这台机器上所有终端、所有项目都会读到它。如果公司项目和个人项目用的是不同的 Key就会互相覆盖你每次切换都得改系统设置极其低效。第二系统环境变量的修改往往需要重启终端甚至重启系统才能生效调试成本高。你在排查一个连接问题时改完变量发现没生效会误以为是配置写错了实际上是环境没刷新。第三不同操作系统对环境变量的处理方式不一样。Windows 用set和系统属性面板Linux 和 macOS 用export和 shell 配置文件语法和生效范围都有差异。把配置绑死在系统层等于把自己锁死在某一台机器上。2.2 分层配置的核心模型我更推荐的做法是把配置分成三层从外到内依次是系统层、用户层、项目层。每一层负责不同粒度的信息优先级从低到高。系统层放的是最通用的东西比如可执行文件的路径、基础的运行时依赖。这一层你基本不用为 Claude Code 单独做什么装好 Node 环境、确保claude命令能被找到就够了。用户层放的是你个人跨项目通用的偏好比如你习惯用的默认模型、你个人的 API Key。这一层通常写在用户主目录下的配置文件里比如~/.claude/settings.json或者 shell 的启动脚本里。项目层放的是这个项目专属的配置比如这个项目要用哪个模型、要不要开启某些实验性功能、工作目录的边界在哪里。这一层写在项目根目录下的.claude/settings.json里跟着代码仓库走换机器拉下来就能用。这样分层之后你换机器只需要保证系统层和用户层就位项目层的配置跟着仓库自动同步。换项目时项目层的配置会自动覆盖用户层的默认值不需要你手动切换。2.3 配置文件与环境变量的分工这里要澄清一个常见误区配置文件和环境变量不是二选一的关系而是各司其职。环境变量适合放敏感信息和机器相关的路径。比如 API Key你不应该把它写进项目配置文件然后提交到仓库里那等于把钥匙挂在门上。正确的做法是把 Key 放在环境变量里配置文件里只写引用。配置文件适合放结构化的偏好设置。比如你想指定默认模型、想设置某些功能的开关、想定义权限规则这些用 JSON 写比用一堆环境变量清晰得多也更容易版本管理。我一般的做法是项目里的.claude/settings.json写非敏感的配置敏感信息通过环境变量注入然后在文档里说明需要设置哪些环境变量。这样既保证了配置的可移植性又保证了安全性。3. 核心细节解析环境变量、settings.json 与 PathMux 的配合3.1 环境变量的设置位置与生效范围环境变量这东西设置的位置不同生效的范围和时机就完全不同。我把它分成四种常见位置你可以对照自己的场景选择。设置位置生效范围生效时机适用场景系统属性面板全系统重启终端或系统Windows 上长期使用的通用变量shell 启动脚本当前用户所有终端新开终端Linux/macOS 个人通用配置项目启动脚本当前项目执行脚本时项目专属变量随项目走命令行临时设置当前命令立即临时调试、一次性覆盖在 Linux 和 macOS 上如果你把export写进~/.bashrc或~/.zshrc那新开的每个终端都会带上这个变量。但要注意如果你用的是 zsh写进~/.bashrc是不生效的这是新手最常踩的坑之一。判断自己用的是哪个 shell敲echo $SHELL看一眼就行。在 Windows 上图形界面的系统属性面板设置的是持久变量但已经打开的终端不会自动刷新。你改完之后要么关掉重开要么在 PowerShell 里手动刷新一下环境。临时用的话PowerShell 里用$env:变量名值cmd 里用set 变量名值但这两个都只在当前窗口有效。3.2 settings.json 的层级与优先级Claude Code 的配置文件有多个可能的位置优先级从高到低大致是项目级配置、用户级配置、系统级默认。项目级的.claude/settings.json会覆盖用户级的~/.claude/settings.json。这个设计的好处是你可以在用户级配置里放一套通用的默认值然后在具体项目里只覆盖需要改的那几项。比如用户级配置里默认用某个模型项目 A 想换一个就只在项目 A 的配置文件里写模型这一项其他配置自动继承。配置文件的格式是 JSON写的时候要注意几点。第一JSON 不支持注释别想着在里面写//说明会解析失败。第二字符串要用双引号不能用单引号。第三最后一项后面不能有多余的逗号这是 JSON 解析报错的高频原因。一个典型的项目级配置大概长这样{ model: claude-sonnet-4-20250514, permissions: { allow: [Read, Write, Bash(git status)], deny: [Bash(rm -rf)] }, env: { PROJECT_ROOT: /home/user/projects/myapp } }这里的env字段可以让你在配置文件里定义环境变量这些变量会在 Claude Code 运行时注入。但再次强调敏感信息不要写在这里。3.3 PathMux 在多环境中的角色PathMux 这个词在 Claude Code 的语境里通常指的是对路径和命令的复用与切换机制。简单说它解决的是“同一个工具在不同环境下路径不一样”的问题。举个实际例子。你在本地开发时项目路径是/Users/you/project到了服务器上变成/var/www/project。如果配置里写死了绝对路径换环境就废了。PathMux 的思路是用变量或者相对路径来表达让同一份配置在不同机器上都能解析到正确的路径。在 Claude Code 里你可以通过环境变量来传递这些路径信息然后在配置里引用。比如在本地 shell 里设置PROJECT_ROOT指向本地路径在服务器上设置同一个变量指向服务器路径配置文件里统一用这个变量。这样配置文件本身不用改换环境只需要改环境变量。这个思路和很多构建工具处理路径的方式是一致的核心就是把变化的部分抽出来让不变的部分保持稳定。4. 实操过程从零搭建一套可切换的多环境配置4.1 基础环境准备与安装确认在动手配多环境之前先把基础环境确认一遍。Claude Code 依赖 Node.js 运行时所以第一步是确认 Node 装好了而且版本不能太老。node --version npm --version如果这两条命令能正常输出版本号说明基础环境没问题。如果提示找不到命令那就得先装 Node。Windows 用户去官网下载安装包Linux 用户可以用包管理器macOS 用户可以用 Homebrew。装完之后重新开一个终端再验证。接下来确认 Claude Code 本身能不能跑起来claude --version如果这条命令报错说明 Claude Code 没装好或者没在 PATH 里。安装方式通常是通过 npm 全局安装装完之后 npm 的全局 bin 目录需要在 PATH 里否则命令找不到。这是新手最常见的“装完了但用不了”的原因。4.2 用户级配置的建立基础环境就绪后先建立用户级配置。这个配置放在你的主目录下对所有项目生效。在 Linux 和 macOS 上我建议把通用的环境变量写进 shell 启动脚本。先确认自己用的是哪个 shellecho $SHELL如果是/bin/zsh就编辑~/.zshrc如果是/bin/bash就编辑~/.bashrc。在文件末尾加上export ANTHROPIC_API_KEY你的密钥 export CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514保存后执行source ~/.zshrc或source ~/.bashrc让配置立即生效或者直接新开一个终端。验证一下echo $ANTHROPIC_API_KEY能打印出你设置的值就说明生效了。在 Windows 上如果你用的是 PowerShell可以编辑 PowerShell 的 profile 文件路径通常是$PROFILE。在里面加上$env:ANTHROPIC_API_KEY你的密钥 $env:CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514保存后重启 PowerShell 即可。4.3 项目级配置的建立用户级配置搞定后进入具体项目目录建立项目级配置。在项目根目录下创建.claude文件夹里面放settings.json。mkdir -p .claude然后创建配置文件。这里的关键是只写这个项目需要覆盖的配置不要把所有东西都抄一遍。比如这个项目要用不同的模型就只写模型{ model: claude-opus-4-20250514 }如果这个项目需要特定的权限规则比如只允许读取不允许写入就加上权限配置。如果这个项目需要引用某个环境变量来定位路径就在env字段里定义。创建完之后建议把.claude/settings.json提交到版本控制这样团队其他人拉下来就能用同一套配置。但如果有敏感信息一定要用环境变量引用不要把明文写进去。4.4 多环境切换的实操演示现在假设你有两个环境本地开发机和远程服务器。本地用一套 Key服务器用另一套本地项目路径和服务器不一样本地想用快速模型服务器想用更强的模型。本地环境的用户级配置里设置本地 Key 和本地路径变量export ANTHROPIC_API_KEY本地密钥 export PROJECT_ROOT/Users/you/projects/myapp服务器环境的用户级配置里设置服务器 Key 和服务器路径export ANTHROPIC_API_KEY服务器密钥 export PROJECT_ROOT/var/www/myapp项目级配置文件里统一引用变量不写死路径{ model: claude-sonnet-4-20250514, env: { WORK_DIR: ${PROJECT_ROOT} } }这样同一份项目配置在本地和服务器上都能正确解析到各自的路径。切换环境时你不需要改项目里的任何文件只需要保证对应机器的用户级环境变量设置正确。如果临时想覆盖某个配置比如这次想用另一个模型直接在命令行里临时设置CLAUDE_DEFAULT_MODELclaude-opus-4-20250514 claude这条命令只在当前这次执行中生效不会影响其他终端和后续使用。5. 常见问题与排查技巧实录5.1 配置不生效的排查顺序配置改完发现没生效这是最高频的问题。我的排查顺序是这样的。第一步确认改的是哪个文件。很多人改了~/.bashrc但自己用的是 zsh那当然不生效。先echo $SHELL确认 shell 类型。第二步确认配置有没有被加载。用echo $变量名看变量是否存在。如果不存在说明启动脚本没被读取或者写错了位置。第三步确认配置文件的位置对不对。Claude Code 读的是项目根目录下的.claude/settings.json如果你在子目录里创建它是读不到的。确认当前工作目录是不是项目根目录。第四步确认 JSON 格式有没有错。JSON 对格式很严格多一个逗号、少一个引号都会导致整个文件解析失败。可以用在线的 JSON 校验工具检查一下或者用python -m json.tool settings.json验证。5.2 环境变量冲突与覆盖问题当同一个变量在多个地方被设置时到底哪个生效这取决于设置的时机和位置。一般来说后设置的覆盖先设置的。命令行临时设置优先级最高因为它是在执行命令的那一刻注入的。项目级配置里的env字段次之。用户级 shell 配置再次之。系统级最低。如果你发现某个变量的值和预期不符可以用env | grep 变量名看看当前终端里所有相关的变量确认是不是被别的地方覆盖了。在 Windows PowerShell 里用Get-ChildItem Env:列出所有环境变量。还有一种情况是变量名拼写不一致。比如你设置的是ANTHROPIC_API_KEY但程序读的是ANTHROPIC_KEY那自然读不到。这种问题只能靠仔细核对文档和配置来避免。5.3 跨平台路径问题的处理Windows 和 Linux 的路径分隔符不一样Windows 用反斜杠Linux 用正斜杠。如果你在配置里写死了路径跨平台时就会出问题。处理办法是尽量用相对路径或者用环境变量传递路径。如果必须写绝对路径在 Windows 上用正斜杠通常也能被识别但最稳妥的还是用变量。另外Windows 上路径里有空格是常见情况比如C:\Program Files\...。在命令行里引用这种路径时记得用引号包起来否则会被当成两个参数。5.4 常见问题速查表现象可能原因排查方法命令找不到PATH 未包含安装目录检查 npm 全局 bin 是否在 PATH配置不生效改错了 shell 配置文件确认 $SHELL 与编辑的文件一致JSON 解析失败格式错误多余逗号或引号用 json.tool 校验变量值为空变量名拼写错误或未加载echo 变量名确认换机器后路径错误配置里写死了绝对路径改用环境变量或相对路径模型不对项目配置未覆盖用户配置检查项目级 settings.json5.5 几个我踩过的坑第一个坑是以为改了配置文件就立即生效。实际上很多配置需要重启终端或者重新加载才会被读取。我一开始改完就测试发现没变化折腾半天才发现是没刷新。第二个坑是在项目配置文件里写了 API Key然后不小心提交到了仓库。虽然发现后立刻撤销了但这件事让我养成了敏感信息一律走环境变量的习惯。第三个坑是 Windows 上用了 PowerShell 的临时变量设置然后换了个 cmd 窗口发现变量没了。临时变量只在当前窗口有效跨窗口是不共享的这个一定要记住。第四个坑是 JSON 文件里写了注释导致解析失败。JSON 标准不支持注释任何注释都会导致解析错误。想写说明的话可以单独写一个 README 文件。6. 进阶技巧让多环境切换更顺滑6.1 用脚本封装环境切换如果你经常在多个环境之间切换可以写一个小脚本把切换动作封装起来。比如在项目根目录放一个env-local.sh和env-server.sh里面分别 export 对应的变量用的时候 source 一下就行。# env-local.sh export ANTHROPIC_API_KEY本地密钥 export PROJECT_ROOT/Users/you/projects/myapp export CLAUDE_DEFAULT_MODELclaude-sonnet-4-20250514# env-server.sh export ANTHROPIC_API_KEY服务器密钥 export PROJECT_ROOT/var/www/myapp export CLAUDE_DEFAULT_MODELclaude-opus-4-20250514用的时候source env-local.sh就切到本地配置source env-server.sh就切到服务器配置。这样比手动改系统环境变量快得多也不容易出错。6.2 配置文件的版本管理策略项目级的.claude/settings.json建议提交到仓库但要注意里面不能有敏感信息。用户级的配置不要提交因为那是你个人的偏好而且可能包含密钥。如果团队协作可以在仓库里放一个settings.example.json作为模板里面写清楚需要哪些配置项但不写具体值。新人拉下来之后复制一份改成自己的settings.json再填入自己的环境变量。6.3 多项目并行的隔离思路如果你同时维护多个项目每个项目都有自己的配置需求那项目级配置的隔离就很重要。核心原则是项目配置只写这个项目特有的东西通用的东西放用户级。比如所有项目都用同一个 API Key那就把 Key 放用户级环境变量项目配置里不写。项目 A 需要特殊权限规则就只在项目 A 的配置里写权限。项目 B 需要不同模型就只在项目 B 的配置里写模型。这样每个项目的配置文件都很短容易维护也不容易互相干扰。我在实际使用中发现把配置分层之后换机器和换项目的成本大幅下降。以前换一台机器要折腾半小时现在只要保证用户级环境变量设置好项目拉下来就能直接跑。这个思路不只适用于 Claude Code很多命令行工具的多环境管理都可以套用同样的逻辑。