环境变量本地持久化管理方案：Anthropic API 凭证管理为例

共计 8521 个字符，预计需要花费 22 分钟才能阅读完成。

最近在使用 Claude Code 的过程中我会经常需要本地持久化配置这两个环境变量，ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN，这里面包含非常敏感的 Token 信息，我之前一直都是通过 dotfiles 来配置 Zsh 的 env ，但显然这个 Token 不方便提交到 Git 中进行管理。而如果每次都手动进行 export 会比较麻烦，也容易出错，所以本文就探讨一下更好的方式来持久化配置环境变量，每次打开终端都自动加载，并确保 Token 的安全性。

核心原理

在深入具体操作之前，理解环境变量的工作原理至关重要。环境变量的本质是操作系统为进程提供的一组键值对数据。当你在终端中运行任何程序时，该程序会继承当前 Shell 进程的所有环境变量。这意味着，如果我们在 Shell 的配置文件中定义这些变量，每次 Shell 启动时都会自动加载它们，后续启动的任何子进程都能访问这些变量。

配置持久化的工作流通常是这样的：

Shell 读取配置文件（如 .bashrc、.zshrc 等）
配置文件中的 export 语句将变量添加到 Shell 的环境中
所有在该 Shell 中启动的进程都能访问这些环境变量
当关闭终端并重新打开时，新的 Shell 进程会再次读取配置文件，重新设置这些变量

这就是为什么我们说"持久化"——变量的定义被存储在磁盘上的配置文件中，即使重启计算机也不会丢失。

方案一：直接写入 Shell 配置文件（最简单的方法）

1. macOS / Linux（Bash Shell）

如果你使用的是较早版本的 macOS 或 Linux 系统，默认的 Shell 可能是 Bash。配置过程非常直接。

步骤一：打开配置文件

nano ~/.bashrc

这个命令会在终端中打开一个名为 nano 的文本编辑器，显示你主目录下的 .bashrc 文件。如果这是第一次编辑该文件，它可能是空的。

步骤二：添加环境变量

将光标移动到文件的末尾，添加以下两行：

export ANTHROPIC_BASE_URL="https://your-api-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="your-auth-token-here"

这里需要替换：

https://your-api-endpoint.example.com 为你实际使用的 API 端点 URL
your-auth-token-here 为你的 Anthropic 认证令牌

关键字 export 的作用是将这些变量标记为"导出"，使得所有子进程都能访问它们。

步骤三：保存文件

在 nano 编辑器中，按以下快捷键保存：

按 Ctrl + O（字母 O，不是数字 0）
按 Enter 确认文件名
按 Ctrl + X 退出编辑器

步骤四：立即生效

配置文件修改后，新打开的终端窗口会自动加载这些变量。但如果你想在当前终端立即生效，运行：

source ~/.bashrc

这个命令会在当前 Shell 进程中重新读取并执行 .bashrc 文件。

步骤五：验证配置

确保配置成功，在终端中运行：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

如果输出显示了你设置的值，说明配置成功。

2. macOS / Linux（Zsh Shell）

现代 macOS（从 Catalina 版本开始）和许多现代 Linux 发行版默认使用 Zsh Shell，它比 Bash 提供了更强大的功能和更好的交互体验。

如何判断你的 Shell 类型

在终端中运行：

echo $SHELL

如果输出包含 zsh，那么你正在使用 Zsh；如果包含 bash，则使用 Bash。

配置步骤

Zsh 的配置方式与 Bash 基本相同，只是配置文件的路径不同。编辑 ~/.zshrc 文件：

nano ~/.zshrc

添加相同的环境变量定义：

export ANTHROPIC_BASE_URL="https://your-api-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="your-auth-token-here"

保存文件后，运行：

source ~/.zshrc

验证配置：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

为什么要区分 Bash 和 Zsh

虽然两者都是 Shell，但它们读取的配置文件不同。如果你在 Bash 中修改了 .bashrc，而你的系统默认使用 Zsh，那么这些变量不会被加载。因此，正确识别你的 Shell 类型是至关重要的。

3. Windows（PowerShell）

Windows 系统的环境变量配置有两种方法：命令行和图形界面。

方法一：通过 PowerShell 命令行设置（推荐）

打开 PowerShell 并以管理员权限运行（右键点击 PowerShell 图标，选择"以管理员身份运行"），然后执行：

[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-api-endpoint.example.com", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-auth-token-here", "User")

这个命令使用了 .NET 环境 API 来设置环境变量。参数说明如下：

第一个参数：环境变量的名称
第二个参数：环境变量的值
第三个参数：变量的作用域，User 表示当前用户级别，Machine 表示系统级别（需要管理员权限，对所有用户生效）

关于作用域的选择：

选择 User 时，变量只对当前用户生效，重启电脑后依然有效
选择 Machine 时，变量对系统中的所有用户生效，但修改时需要管理员权限

设置完成后的验证

重启 PowerShell 或整个系统，然后在 PowerShell 中运行：

$env:ANTHROPIC_BASE_URL
$env:ANTHROPIC_AUTH_TOKEN

如果能输出你设置的值，说明配置成功。注意在 PowerShell 中，访问环境变量需要使用 $env: 前缀。

方法二：通过图形界面设置

如果你不习惯使用命令行，也可以通过 Windows 的图形界面来设置环境变量：

右键点击"此电脑"或"我的电脑"，选择"属性"
点击"高级系统设置"
在弹出的"系统属性"对话框中，点击"环境变量"按钮
在"用户变量"或"系统变量"部分，点击"新建"按钮
在"变量名"字段中输入 ANTHROPIC_BASE_URL
在"变量值"字段中输入你的 API 端点 URL
点击 OK 保存
重复上述步骤，创建 ANTHROPIC_AUTH_TOKEN 变量

完成后，重启 PowerShell 或 CMD 终端，新的环境变量就会生效。

方案二：使用 .env 文件实现敏感信息分离（更安全）

直接在 Shell 配置文件中写明文的认证令牌存在安全隐患。更好的做法是将敏感信息集中存储在单独的 .env 文件中，然后在 Shell 配置中动态读取。

1. 创建 .env 文件

在你的主目录或项目目录下创建一个 .env 文件。如果是全局配置，创建在主目录：

# ~/.env 文件内容
ANTHROPIC_BASE_URL=https://your-api-endpoint.example.com
ANTHROPIC_AUTH_TOKEN=your-auth-token-here

注意：这里不需要使用 export 关键字，也不需要给值加上引号（虽然加也不错）。.env 文件格式比较简单，就是一行一个 KEY=VALUE 对。

2. 在 Shell 配置中加载 .env 文件

编辑你的 ~/.bashrc 或 ~/.zshrc，在文件末尾添加：

# 如果 ~/.env 文件存在，就加载它
if [ -f ~/.env ]; then
    set -a
    source ~/.env
    set +a
fi

这段代码的含义需要逐行解释：

if [ -f ~/.env ]：这是一个条件检查，-f 选项检查 ~/.env 是否存在且是一个普通文件（不是目录或其他特殊文件）。这种防御性编程的好处是，即使 .env 文件不存在，你的 Shell 配置也不会出错。

set -a：这个命令告诉 Shell 自动将接下来定义的所有变量标记为"导出"。通常，你需要在每个变量前面加 export 关键字才能导出它。但使用 set -a 后，就不需要这样做了。这样做的好处是 .env 文件可以保持简洁，不需要在每一行前面都写 export。

source ~/.env：这个命令读取并执行 .env 文件中的所有变量定义。

set +a：这个命令关闭自动导出模式，恢复到默认行为。这确保了后续定义的变量不会被意外导出。

3. 重启终端并验证

保存 Shell 配置文件后，关闭并重新打开终端窗口（或运行 source ~/.bashrc / source ~/.zshrc），然后验证：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

4. 将 .env 添加到 .gitignore

如果你的项目使用 Git 进行版本控制，千万不要将 .env 文件提交到 Git 仓库，因为它包含敏感信息。在项目根目录的 .gitignore 文件中添加：

.env

这样，Git 会自动忽略 .env 文件，防止敏感信息被意外上传到远程仓库。

5. 为团队成员提供模板

为了帮助新的团队成员快速设置环境，可以在项目中创建一个 .env.example 文件，列出所有需要的变量（但不包含真实的值）：

# .env.example
ANTHROPIC_BASE_URL=https://your-api-endpoint.example.com
ANTHROPIC_AUTH_TOKEN=your-auth-token-here

团队成员可以复制这个文件为 .env，然后填入自己的实际值。

方案三：使用 direnv 实现项目级隔离（最灵活）

如果你需要同时开发多个项目，这些项目可能需要不同的 Anthropic 凭证或其他环境配置。在这种情况下，使用 direnv 工具可以实现项目级别的环境变量隔离，避免污染全局环境。

什么是 direnv

direnv 是一个开源工具，它可以根据你当前所在的目录自动加载和卸载环境变量。当你进入一个使用 direnv 的项目目录时，该项目对应的环境变量会被自动加载；当你离开该目录时，这些变量会被自动卸载。这样，不同的项目可以有完全隔离的环境配置。

1. 安装 direnv

在 macOS 上安装（使用 Homebrew）：

brew install direnv

在 Linux 上安装（以 Ubuntu/Debian 为例）：

sudo apt-get install direnv

在 Windows 上安装（使用 Scoop）：

scoop install direnv

2. 初始化 direnv

安装完成后，需要在你的 Shell 配置文件中添加 direnv 的初始化代码。这样，每当你进入一个目录时，direnv 都会检查是否需要加载环境变量。

对于 Bash，在 ~/.bashrc 末尾添加：

eval "$(direnv hook bash)"

对于 Zsh，在 ~/.zshrc 末尾添加：

eval "$(direnv hook zsh)"

保存后，重启终端使配置生效。

3. 创建 .envrc 文件

在你的项目根目录下创建 .envrc 文件，定义该项目特有的环境变量：

# <project>/.envrc
export ANTHROPIC_BASE_URL="https://your-api-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="your-auth-token-here"

4. 允许 direnv 加载配置

第一次进入项目目录时，direnv 会提示你确认是否允许加载 .envrc 文件（这是一个安全机制，防止恶意脚本自动执行）。运行以下命令来允许加载：

direnv allow

5. 使用 direnv

现在，每当你 cd 进这个项目目录时，.envrc 中定义的所有变量都会自动加载。你可以验证：

echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

当你离开项目目录进入其他目录时，这些变量会自动卸载。这确保了不同项目的环境互相不干扰。

direnv 的高级用法

direnv 的功能远不止简单的变量定义。你可以在 .envrc 中编写任意 Shell 脚本，比如：

# .envrc 示例：动态路径管理和条件加载
export ANTHROPIC_BASE_URL="https://your-api-endpoint.example.com"
export ANTHROPIC_AUTH_TOKEN="your-auth-token-here"

# 添加项目的 bin 目录到 PATH
PATH_add bin

# 条件加载：根据不同的环境变量设置不同的配置
if [ "$ENV" = "production" ]; then
    export DEBUG=false
else
    export DEBUG=true
fi

这种灵活性使得 direnv 特别适合复杂的多项目开发场景。

方案对比与选择建议

不同的方案各有优缺点，适用于不同的场景。下表总结了各个方案的特点，帮助你做出最合适的选择：

方案	适用场景	安全性	可维护性	复杂度
直接写 .bashrc/.zshrc	单台机器，固定值，个人项目	低（明文存储）	低（改配置需编辑文件）	简单
~/.env + source	多个变量，全局共用	中（单独文件，可加入 .gitignore）	中（集中管理，但仍需手动编辑）	中等
direnv + .envrc	多项目，不同凭证	较高（项目级隔离，敏感信息不污染全局）	较高（项目自带配置，易于分享）	较复杂
密码管理器 + CLI 脚本	企业/团队环境	高（加密存储，严格访问控制）	高（自动化管理）	复杂

选择建议：

个人项目开发：如果你的项目比较简单，只需要配置几个环境变量，直接使用第一种方案（写入 .bashrc 或 .zshrc）即可，足够简单高效。
中等规模项目：如果你的项目中包含多个需要不同配置的模块或子项目，使用第二种方案（.env 文件）会更加清晰和易于维护。
多项目开发：如果你同时开发多个项目，且这些项目需要不同的 Anthropic 凭证，使用 direnv 可以完全隔离每个项目的环境配置，避免变量冲突和意外污染。
企业团队环境：在企业环境中，凭证管理通常有严格的安全要求。建议集成专业的密钥管理系统，如 AWS Secrets Manager、HashiCorp Vault、1Password CLI 或 Bitwarden CLI 等。

与 Claude Code 和 MCP 的集成

如果你在使用 Claude Code（Anthropic 的代码编辑器）或 MCP（Model Context Protocol）服务，需要确保这些工具能正确读取你配置的环境变量。

1. Claude Code 编辑器

Claude Code 通常集成在 VS Code 或 JetBrains IDE 中。要让 Claude Code 读取新配置的环境变量，需要：

重新启动编辑器进程：完全关闭编辑器窗口（包括后台进程），然后重新启动。编辑器启动时会继承新的环境变量。

在编辑器内的终端运行 CLI：如果你在编辑器内打开终端来运行命令行工具或脚本，那个终端会自动继承编辑器进程的环境变量，包括你新设置的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN。

2. MCP 服务器配置

如果你需要在 MCP 服务器中使用这些环境变量，可以在 MCP 配置文件中直接引用。MCP 配置通常存储在 ~/.claude/mcp_servers.json 或项目的 .claude/mcp_servers.json 中：

{
  "mcpServers": {
    "your-custom-mcp": {
      "command": "python",
      "args": ["-m", "your_mcp_module"],
      "env": {
        "ANTHROPIC_BASE_URL": "${ANTHROPIC_BASE_URL}",
        "ANTHROPIC_AUTH_TOKEN": "${ANTHROPIC_AUTH_TOKEN}"
      }
    }
  }
}

这个配置告诉 MCP 框架在启动 your-custom-mcp 服务时，将当前 Shell 的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN 环境变量传递给该服务。

注意：具体的变量引用语法可能因 MCP 工具版本而异。建议查看你使用的 MCP 工具的官方文档以获取最准确的语法。

快速参考指南

为了方便快速操作，这里提供了各个操作系统的完整命令序列。

macOS / Linux（Zsh，推荐）

# 1. 打开 ~/.zshrc
nano ~/.zshrc

# 2. 在末尾添加以下内容
# export ANTHROPIC_BASE_URL="https://your-endpoint"
# export ANTHROPIC_AUTH_TOKEN="your-token"
# （需要手动编辑，按 Ctrl+O, Enter, Ctrl+X 保存）

# 3. 立即生效
source ~/.zshrc

# 4. 验证
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

macOS / Linux（Bash）

# 1. 打开 ~/.bashrc
nano ~/.bashrc

# 2. 在末尾添加以下内容
# export ANTHROPIC_BASE_URL="https://your-endpoint"
# export ANTHROPIC_AUTH_TOKEN="your-token"
# （需要手动编辑，按 Ctrl+O, Enter, Ctrl+X 保存）

# 3. 立即生效
source ~/.bashrc

# 4. 验证
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

Windows（PowerShell，管理员模式）

# 1. 以管理员身份打开 PowerShell

# 2. 设置环境变量
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://your-endpoint", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_AUTH_TOKEN", "your-token", "User")

# 3. 重启 PowerShell

# 4. 验证
$env:ANTHROPIC_BASE_URL
$env:ANTHROPIC_AUTH_TOKEN

使用 .env 文件（跨平台）

# 1. 在主目录创建 ~/.env
nano ~/.env

# 2. 添加以下内容
# ANTHROPIC_BASE_URL=https://your-endpoint
# ANTHROPIC_AUTH_TOKEN=your-token

# 3. 编辑 Shell 配置，添加以下代码
# 对于 Bash，编辑 ~/.bashrc；对于 Zsh，编辑 ~/.zshrc
if [ -f ~/.env ]; then
    set -a
    source ~/.env
    set +a
fi

# 4. 重启终端或运行 source ~/.bashrc (或 ~/.zshrc)

# 5. 验证
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_AUTH_TOKEN

常见问题与故障排除

Q1：设置了环境变量，但在新终端中看不到？

原因：新终端窗口没有读取更新的配置文件。

解决：

完全关闭所有终端窗口，然后重新打开一个新的终端窗口
或者在当前终端中运行 source ~/.bashrc 或 source ~/.zshrc

Q2：在一个终端中能看到环境变量，但在 IDE 内的终端看不到？

原因：IDE 启动时没有加载最新的 Shell 配置。

解决：完全退出 IDE（包括后台进程），然后重新启动它。

Q3：如何检查环境变量是否被导出？

运行：

env | grep ANTHROPIC

这会显示所有名称包含 "ANTHROPIC" 的环境变量。如果看不到你设置的变量，说明它们没有被正确导出。

Q4：在 .env 文件中使用的变量在 Shell 中看不到，但直接写在 .bashrc 中却能看到？

原因：可能是 source ~/.env 命令没有被执行，或者 .env 文件的路径不正确。

解决：

检查 .bashrc 或 .zshrc 中的 source ~/.env 代码是否正确
确保 ~/.env 文件确实存在
运行 ls -la ~/.env 检查文件是否存在

Q5：如何临时取消设置的环境变量？

运行：

unset ANTHROPIC_BASE_URL
unset ANTHROPIC_AUTH_TOKEN

但这只会在当前终端会话中生效。重新打开终端后，变量会重新被加载。

进阶安全考虑

上述方案都是将凭证以某种形式存储在本地磁盘。对于企业级应用或高安全需求的场景，可能需要更高级的解决方案。比如集成密码管理器（1Password，Bitwarden，KeePass 等），直接从加密存储中读取密钥。或者使用企业级别的密钥管理系统，比如 AES Secrets Manager，HashiCorp Vault，Azure Key Vault，Google Cloud Secret Manager 等。