Claude Code: 环境变量与开发配置

Q: API Key 写在 .env 里安全吗？

本地开发可以，但要确保 .env 在 .gitignore 中。CI 环境用 Secrets 管理。

Q: 如何验证环境变量是否生效？

在 Claude Code 中运行 /config ，查看当前配置。或 echo $ANTHROPIC_API_KEY 。

最后更新：2026-08-31

环境变量是 Claude Code 配置的"控制面板"——API 密钥、模型选择、输出偏好，一切都在环境变量中掌控。

💡 提示：环境变量优先级最高，覆盖 CLAUDE.md 和 settings.json。适合需要动态切换的配置（如 API Key、模型选择）。

📋 前置知识：第二十一章实战：Chrome 扩展与并行任务

1. 你将学到

所有环境变量详解
开发配置最佳实践
多环境切换方案
调试与诊断配置
团队配置管理

2. 环境变量详解

(1) 核心变量

变量	必需	说明	示例
`ANTHROPIC_API_KEY`	✅	API 密钥	`sk-ant-api03-xxx`
`ANTHROPIC_BASE_URL`	❌	API 地址	`https://api.deepseek.com`
`CLAUDE_MODEL`	❌	默认模型	`claude-sonnet-4-20250514`

(2) 行为控制变量

变量	说明	默认值	示例
`CLAUDE_STYLE`	输出样式	`default`	`concise`
`CLAUDE_LANGUAGE`	输出语言	`en`	`zh`
`CLAUDE_AUTO_TEST`	修改后自动测试	`false`	`true`
`CLAUDE_AUTO_COMMIT`	自动提交变更	`false`	`true`
`CLAUDE_MAX_TURNS`	最大迭代轮数	`50`	`20`
`CLAUDE_TIMEOUT`	单次操作超时(秒)	`300`	`60`

(3) 调试变量

变量	说明	默认值
`CLAUDE_DEBUG`	启用调试日志	`false`
`CLAUDE_HOOK_DEBUG`	钩子调试日志	`false`
`CLAUDE_LOG_LEVEL`	日志级别	`info`
`CLAUDE_LOG_FILE`	日志文件路径	-

▶ 示例 1: 环境变量配置

BASH

# 基础配置
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
export CLAUDE_STYLE="concise"
export CLAUDE_LANGUAGE="zh"

# 开发调试
export CLAUDE_DEBUG=true
export CLAUDE_LOG_LEVEL=debug
export CLAUDE_HOOK_DEBUG=1

# 性能优化
export CLAUDE_MAX_TURNS=20
export CLAUDE_TIMEOUT=120

3. 开发配置最佳实践

(1) 配置文件层级

TEXT 📖 仅展示

优先级（从高到低）：
1. 命令行参数       --model claude-opus-4-20250514
2. 环境变量         CLAUDE_MODEL=claude-opus-4-20250514
3. 项目 .env        .env 文件中的变量
4. 项目 CLAUDE.md   项目级配置
5. 全局 settings    ~/.claude/settings.json
6. 全局 CLAUDE.md   ~/.claude/CLAUDE.md
7. 默认值           内置默认配置

(2) .env 文件管理

BASH

# 项目 .env 文件
# .env
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise

# .env.development（开发环境）
ANTHROPIC_API_KEY=sk-ant-api03-dev-key
CLAUDE_DEBUG=true

# .env.production（生产相关，不包含 API Key）
CLAUDE_STYLE=verbose
CLAUDE_MAX_TURNS=10

# 确保 .env 在 .gitignore 中
echo ".env*" >> .gitignore

▶ 示例 2: 使用 direnv 自动切换

BASH

# 项目A: .envrc
export ANTHROPIC_API_KEY="sk-ant-api03-project-a"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
export CLAUDE_STYLE="default"

# 项目B: .envrc
export ANTHROPIC_API_KEY="sk-deepseek-xxxxx"
export ANTHROPIC_BASE_URL="https://api.deepseek.com"
export CLAUDE_MODEL="deepseek-chat"
export CLAUDE_STYLE="concise"

# 进入目录自动切换
cd project-a  # 自动加载项目A配置
cd project-b  # 自动切换到项目B配置

4. 多环境管理

(1) 环境配置矩阵

环境	API Key	模型	样式	调试
开发	Dev Key	Sonnet	verbose	on
测试	Test Key	Sonnet	default	off
CI	CI Key	Sonnet	JSON	off
个人	Personal	Opus	concise	off

(2) 环境切换方案

BASH

# 方案1：Shell alias
alias claude-dev='ANTHROPIC_API_KEY=$DEV_KEY CLAUDE_DEBUG=true claude'
alias claude-ci='ANTHROPIC_API_KEY=$CI_KEY claude --headless --output json'
alias claude-personal='ANTHROPIC_API_KEY=$PERSONAL_KEY CLAUDE_MODEL=claude-opus-4-20250514 claude'

# 方案2：direnv（推荐）
# 每个项目目录自动加载对应 .envrc

# 方案3：配置文件
claude --env-file ./configs/production.env

▶ 示例 3: 团队共享配置

BASH

# .env.example（提交到 git，不含密钥）
ANTHROPIC_API_KEY=your-api-key-here
CLAUDE_MODEL=claude-sonnet-4-20250514
CLAUDE_STYLE=concise
CLAUDE_AUTO_TEST=true

# 每个开发者复制并填写
cp .env.example .env
# 编辑 .env 填入自己的 API Key

5. 调试与诊断

(1) 启用调试模式

BASH

# 启用全部调试
export CLAUDE_DEBUG=true
export CLAUDE_LOG_LEVEL=debug
export CLAUDE_HOOK_DEBUG=1

# 日志输出到文件
export CLAUDE_LOG_FILE=/tmp/claude-debug.log

# 运行 Claude Code
claude "测试任务"

# 查看日志
tail -f /tmp/claude-debug.log

(2) 常见诊断

TEXT 📖 仅展示

# 问题：Claude Code 连接失败
export CLAUDE_DEBUG=true
claude "test"
# 检查日志中的 HTTP 请求和响应

# 问题：MCP 服务器不工作
claude /mcp
# 查看已连接的 MCP 服务器状态

# 问题：钩子不触发
export CLAUDE_HOOK_DEBUG=1
claude "修改文件"
# 查看钩子触发日志

6. 综合示例：完整开发配置

BASH

# Alice 的完整开发配置

# ~/.zshrc（全局配置）
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxx"
export CLAUDE_MODEL="claude-sonnet-4-20250514"
export CLAUDE_STYLE="concise"
export CLAUDE_LANGUAGE="zh"
export CLAUDE_AUTO_TEST="true"

# 项目 .envrc
export CLAUDE_MODEL="claude-opus-4-20250514"  # 此项目用 Opus
export CLAUDE_MAX_TURNS="30"

# ~/.claude/settings.json
{
  "output": {
    "showDiff": true,
    "autoTest": true
  },
  "permissions": {
    "autoApprove": ["Read", "Write"],
    "requireConfirm": ["Bash"]
  }
}

# ~/.claude/CLAUDE.md（全局偏好）
# TypeScript 严格模式，ES Module，JSDoc 注释

❓ 常见问题

Q 环境变量和 CLAUDE.md 哪个优先？

A 环境变量优先。CLAUDE.md 写偏好和约定，环境变量写运行时配置（如 API Key）。

Q API Key 写在 .env 里安全吗？

A 本地开发可以，但要确保 .env 在 .gitignore 中。CI 环境用 Secrets 管理。

Q CLAUDE_MAX_TURNS 设多少合适？

A 日常 20-30 足够。复杂任务可以设到 50。设太小可能导致任务未完成就停止。

Q 调试模式影响性能吗？

A 影响。调试日志会增加 I/O 开销。只在排查问题时开启，日常关闭。

Q 如何验证环境变量是否生效？

A 在 Claude Code 中运行 /config，查看当前配置。或 echo $ANTHROPIC_API_KEY。

Q 多环境一定要用 direnv 吗？

A 不一定。Shell alias 和 .env 文件也可以。direnv 最方便（自动切换），但需要额外安装。

📖 小节

核心环境变量：ANTHROPIC_API_KEY、CLAUDE_MODEL、CLAUDE_STYLE
配置优先级：命令行 > 环境变量 > .env > CLAUDE.md > settings
direnv 实现目录级自动配置切换
.env.example 提交 git，.env 加入 .gitignore
调试变量只在排查问题时开启

📝 作业

基础题（难度⭐）：配置 CLAUDE_STYLE 和 CLAUDE_LANGUAGE 环境变量，验证输出样式和语言变化。
进阶题（难度⭐⭐）：使用 direnv 为两个项目配置不同的 API Key 和模型，验证自动切换。
挑战题（难度⭐⭐⭐）：设计团队级环境配置方案，覆盖开发/测试/CI 三种环境，确保密钥安全。

Web-Tutorial 技术团队

由多位开发者共同维护的编程教程平台。每篇教程由对应领域的开发者编写和审核，确保内容准确可靠。如发现任何问题，欢迎向我们反馈。

关于我们

Claude Code: 环境变量与开发配置

1. 你将学到

2. 环境变量详解

(1) 核心变量

(2) 行为控制变量

(3) 调试变量

▶ 示例 1: 环境变量配置

3. 开发配置最佳实践

(1) 配置文件层级

(2) .env 文件管理

▶ 示例 2: 使用 direnv 自动切换

4. 多环境管理

(1) 环境配置矩阵

(2) 环境切换方案

▶ 示例 3: 团队共享配置

5. 调试与诊断

(1) 启用调试模式

(2) 常见诊断

6. 综合示例：完整开发配置

❓ 常见问题

📖 小节

📝 作业

🙏 帮我们做得更好