在使用 Claude Code 进行本地 AI 辅助编程时，环境变量的正确配置是确保工具能够顺利调用 Anthropic API 并稳定运行的核心前提。许多开发者在初次部署时，常因路径错误、权限不足或变量名拼写错误导致连接失败。本文将提供一套标准化的步骤清单，帮助你在主流操作系统中快速完成本地任务的环境变量设置，确保开发流程顺畅无阻。
确定关键环境变量与获取密钥
Claude Code 的核心依赖是 Anthropic 的 API 访问权限。在配置系统之前，你需要首先登录 Anthropic 控制台，生成有效的 API Key。目前，Claude Code 主要识别以下两个关键环境变量：
- ANTHROPIC_API_KEY：这是最核心的凭证，用于身份验证和计费。请务必将其保管在安全的地方，切勿提交到版本控制系统中。
- ANTHROPIC_BASE_URL（可选）：如果你使用代理服务器或特定的内部网关，需要在此变量中指定自定义的基础 URL。对于大多数直接调用的用户，此变量可留空，系统将自动使用官方端点。
请复制生成的 API Key，后续步骤将直接使用这一字符串。建议先创建一个纯文本文件临时存放密钥，以便在配置过程中方便复制，避免手动输入错误。
Windows 系统配置步骤
在 Windows 环境中，环境变量可以通过图形界面或 PowerShell 命令进行设置。推荐使用方法以确保配置的持久性和准确性。
方法一：通过 PowerShell 永久设置
打开 PowerShell 终端，执行以下命令以将 API Key 写入当前用户的永久环境变量中：
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "你的API密钥", "User")若要同时设置 Base URL，可追加执行：
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://api.anthropic.com", "User")方法二：通过系统图形界面设置
- 按
Win + R键，输入sysdm.cpl并回车，打开“系统属性”。 - 点击“高级”选项卡，选择“环境变量”。
- 在“用户变量”区域，点击“新建”，变量名填
ANTHROPIC_API_KEY，变量值填入你的密钥。 - 点击确定保存。注意：修改后需重启终端或 IDE 才能生效。
macOS 与 Linux 系统配置步骤
对于基于 Unix 的系统，配置文件通常位于 Shell 的初始化脚本中。根据你使用的默认 Shell（Bash 或 Zsh），操作略有不同。
针对 Bash 用户
编辑 ~/.bashrc 或 ~/.profile 文件，在末尾添加以下行：
export ANTHROPIC_API_KEY="你的API密钥"针对 Zsh 用户（macOS 默认）
编辑 ~/.zshrc 文件，添加相同的内容：
export ANTHROPIC_API_KEY="你的API密钥"保存文件后，务必运行 source ~/.zshrc（或对应的 bash 文件）以使更改立即生效。这一步骤常被新手忽略，导致新开的终端窗口仍无法识别变量。
验证配置与故障排查
配置完成后，验证环境变量是否成功加载至关重要。你可以直接在终端中输入以下命令来检查：
echo $ANTHROPIC_API_KEY如果输出的是你的密钥字符串（或部分掩码后的内容），则说明配置成功。如果输出为空，请检查文件名是否正确，以及是否执行了 source 命令。
若遇到连接拒绝或认证失败的错误，请按以下步骤排查：
- 检查密钥有效性：确认密钥未过期，且账户状态正常。
- 检查拼写：环境变量名必须完全匹配
ANTHROPIC_API_KEY，大小写敏感。 - 重启进程：某些集成开发环境（如 VS Code）可能在启动时缓存环境变量，尝试完全关闭并重新打开编辑器。
- 查看日志：运行 Claude Code 时添加
--verbose参数，查看详细报错信息，定位是网络问题还是凭证问题。
通过以上标准化的步骤，你可以高效地完成 Claude Code 的本地环境搭建。正确的环境变量管理不仅能提升开发效率，还能保障 API 调用的安全性与稳定性。建议在团队项目中，使用 .env 文件或 CI/CD 管道来统一管理这些敏感信息，避免硬编码风险。
本文链接：https://ai-claudecode.cn/doubao/claude-codebdhjblpzzn-azpzyczbz/