Claude Code 安全最佳实践完全指南：API密钥管理、权限设置与生产环境保护

Claude Code 拥有强大的文件操作和命令执行能力，但配置不当可能导致无法挽回的事故。提交 .env 文件、误删生产数据库、将 API 密钥输出到日志——这些都是实际发生过的案例，根源在于没有对 Claude Code 做任何安全防护。

本文从实现层面详细介绍 Claude Code 的安全防护措施，重点不在于概念讲解，而是提供可以直接复制使用的配置和预防代码。

为什么 Claude Code 需要安全措施

与普通文本编辑器不同，Claude Code 具备以下能力：

• 读取、写入、删除任意文件 (Read / Write / Edit / Bash(rm))
• 执行 Shell 命令 (Bash)
• 网络访问 (WebFetch / API 调用)
• 向外部服务发布内容 (GitHub、Slack 等)

这些操作只要用户批准就能执行。问题在于：如果机械式地一直点确认，意外操作就会悄然通过。安全措施的本质是从结构上消除出错的空间。

措施1：API 密钥管理——.env + .gitignore 是基础

绝对不能做的事

// ❌ 直接写在源代码里
const client = new Anthropic({ apiKey: "sk-ant-api03-..." });

// ❌ 写在 CLAUDE.md 或配置文件里
// ANTHROPIC_API_KEY=sk-ant-api03-...

// ❌ 写在 claude -p 的提示词里
// 使用 QIITA_TOKEN=abc123 发布到 Qiita

正确的管理方式

# .env（排除在 git 之外，仅存于本机）
ANTHROPIC_API_KEY=sk-ant-api03-...
QIITA_TOKEN=06b4441b...
SLACK_BOT_TOKEN=xoxb-...
DATABASE_URL=postgresql://...

# 必须加入 .gitignore
.env
.env.*
.env.local
!.env.example   # ← 示例文件可以提交
*.pem
*.key
credentials.json
*-service-account.json

# .env.example（可以提交，值留空）
ANTHROPIC_API_KEY=
QIITA_TOKEN=
SLACK_BOT_TOKEN=
DATABASE_URL=

在代码中读取变量

// ✅ 从环境变量读取
import { config } from "dotenv";
config();

const token = process.env.QIITA_TOKEN;
if (!token) throw new Error("QIITA_TOKEN 未设置，请检查 .env 文件。");

在 CLAUDE.md 中明确禁止事项

## 安全禁止事项
- 不在提示词中包含 API 密钥或 Token
- 不读取并输出 .env 文件的内容
- 不将环境变量的值写入日志或注释
- 不对 process.env 的内容使用 console.log

措施2：提交前扫描敏感信息

即使将 .env 加入 gitignore，也无法防止误写入其他文件或复制粘贴失误。需要引入提交前自动扫描机制。

使用 Hooks 实现提交前检查

.claude/settings.json：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git commit*)",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/secret-scan.mjs"
          }
        ]
      }
    ]
  }
}

scripts/secret-scan.mjs：

import { execSync } from "child_process";

// 获取已暂存的变更
const diff = execSync("git diff --cached").toString();

const PATTERNS = [
  { name: "Anthropic API 密钥", re: /sk-ant-api\d+-[A-Za-z0-9_-]{80,}/ },
  { name: "OpenAI API 密钥", re: /sk-[A-Za-z0-9]{48}/ },
  { name: "AWS 访问密钥", re: /AKIA[0-9A-Z]{16}/ },
  { name: "Slack Token", re: /xox[baprs]-[0-9A-Za-z-]{10,}/ },
  { name: "通用密钥", re: /[Ss]ecret[_-]?[Kk]ey\s*[:=]\s*['"][^'"]{10,}['"]/ },
];

const found = PATTERNS.filter(({ re }) => re.test(diff));

if (found.length > 0) {
  console.error("🚨 发现敏感信息！已中止提交：");
  found.forEach(({ name }) => console.error(`  - ${name}`));
  console.error("\n处理方法：运行 `git reset HEAD <file>` 取消暂存该文件");
  process.exit(1);  // 退出码 1 → Hook 阻止命令执行
}

console.log("✓ 敏感信息扫描：未发现问题");
process.exit(0);

这样，Claude Code 尝试执行 git commit 的瞬间，自动扫描就会启动，一旦检测到泄露即被拦截。

措施3：权限模式配置

Claude Code 的允许/拒绝设置可以在文件级别进行细粒度控制。

.claude/settings.json 的权限配置

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git reset --hard*)",
      "Bash(DROP TABLE*)",
      "Bash(truncate*)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(npm publish*)",
      "Bash(wrangler pages deploy*)"
    ]
  }
}

设置	含义
allow	无需确认，直接执行
deny	完全禁止执行
ask	每次都需要审批

要点：破坏性命令放 deny，写入操作放 ask，读取操作放 allow。

生产环境专用配置文件

生产环境中，限制为只读模式最为安全。

// .claude/settings.production.json
{
  "permissions": {
    "allow": ["Read(**)", "Glob(**)", "Grep(**)", "Bash(git log*)", "Bash(git diff*)"],
    "deny": ["Write(**)", "Edit(**)", "Bash(git push*)", "Bash(rm*)", "Bash(*deploy*)"],
    "ask": []
  }
}

# 在生产环境作业时明确指定配置文件
CLAUDE_SETTINGS=.claude/settings.production.json claude

措施4：生产环境保护

明确隔离连接目标

## CLAUDE.md — 生产环境规则

## 环境判断
- DATABASE_URL 中包含 'prod' 或 'production' 时，视为**生产环境**
- 在生产环境中，以下操作绝对禁止：
  - DROP / TRUNCATE / DELETE（无 WHERE 条件）
  - 数据库迁移（需提前确认）
  - 批量删除文件

## 确认流程
对生产环境的任何变更，必须：
1. 在预发布环境中先行测试
2. 获得用户确认
3. 执行后报告结果

用环境变量控制连接目标

// scripts/db-query.mjs
const env = process.env.NODE_ENV ?? "development";
const dbUrl = process.env.DATABASE_URL;

if (env === "production" && process.argv.includes("--write")) {
  console.error("❌ 向生产环境写入需要 --force-production 标志");
  process.exit(1);
}

措施5：文件操作安全装置

自动化删除前备份

// .claude/settings.json 中的 Hooks
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(rm *)",
        "hooks": [
          {
            "type": "command",
            "command": "echo '⚠️  删除命令即将执行，按 Ctrl+C 可中止。' && sleep 3"
          }
        ]
      }
    ]
  }
}

防止重要文件被误编辑

## CLAUDE.md — 禁止修改的文件

以下文件**绝对不得编辑**：
- .env（包含环境变量和密钥）
- wrangler.toml（Cloudflare 生产配置）
- scripts/deploy.sh（部署脚本）
- .github/workflows/*.yml（CI/CD 配置）

如确需修改，请先征得用户同意。

五大常见误区

1. 事后再加 .gitignore 已为时太晚 已经提交过的 .env 即使加入 gitignore，也依然留在 git 历史中。

# 从历史中彻底删除（注意：需要 force push）
git filter-branch --force --index-filter \
  "git rm --cached --ignore-unmatch .env" \
  --prune-empty --tag-name-filter cat -- --all

# 或者使用 BFG Repo Cleaner

如果已经推送到 GitHub，请务必先轮换 API 密钥再处理历史记录。

2. 将服务账号 JSON 文件放入代码仓库 Google Cloud 或 AWS 的服务账号密钥通常以 .json 文件形式下发，但存入代码仓库十分危险。请将其转为环境变量，或迁移至 Secret Manager（AWS Secrets Manager / GCP Secret Manager）。

3. 用 Bash 工具执行交互式命令 在 claude -p 无头运行时，如果混入了需要交互输入的命令（如 sudo、vim），进程会挂起。请只使用非交互式命令。

4. 在错误信息中包含凭据

// ❌ 危险：API 密钥会出现在日志中
throw new Error(`认证失败：token=${process.env.TOKEN}`);

// ✅ 安全：不输出具体值
throw new Error(`认证失败：请检查 TOKEN 环境变量`);

5. 所有项目共用同一份权限配置 个人项目和工作项目使用同一份 settings.json，会导致工作项目所需的严格限制被个人项目宽松的配置覆盖。请为每个项目单独管理 .claude/settings.json。

安全检查清单

引入 Claude Code 项目时的确认事项：

### 基础配置
- [ ] 已创建 .env 并添加到 .gitignore
- [ ] 已创建 .env.example 并与团队共享
- [ ] 通过 git log 确认现有提交中无敏感信息

### 权限配置
- [ ] 已在 .claude/settings.json 中配置 deny 列表
- [ ] 已将破坏性命令（rm -rf、DROP TABLE 等）加入 deny
- [ ] 已将生产部署命令设置为 ask

### 自动化
- [ ] 已配置提交前敏感信息扫描 Hook
- [ ] 已在 CLAUDE.md 中记录安全禁止事项

### 运维
- [ ] 已制定 API 密钥轮换周期（推荐：90天）
- [ ] 生产环境使用专用的 settings.production.json
- [ ] 已将事故响应流程文档化

总结

Claude Code 的安全不是”施加限制”，而是**“构建一个从结构上杜绝事故的体系”**。

威胁	对策
API 密钥泄露	.env + .gitignore + 敏感信息扫描 Hook
误删文件	deny 列表 + 删除前 Hook
误操作生产环境	生产专用配置 + CLAUDE.md 禁止事项
提交污染	PreToolUse Hook 提交前扫描

配置一次，基本免维护。今天花30分钟完成配置，可以避免未来的重大事故。

相关文章

• Claude Code 权限设置指南
• Claude Code 安全失败案例
• Claude Code + SaaS 集成完全指南
• CLAUDE.md 最佳实践

参考资料

• Claude Code 权限设置官方文档
• 使用 git-filter-branch 删除历史中的敏感信息
• BFG Repo Cleaner