settings.json 全局 vs 项目层级

settings.json 全局 vs 项目层级

基础概念

Claude Code 的所有配置——能允许哪些工具、敏感目录要不要拦、用哪个模型、要不要挂钩子、要不要自动加 Co-Authored-By——最终都汇聚到一个名字叫 settings.json 的 JSON 文件里。但这个文件不止一份。Claude Code 把它沿用户、项目、个人覆盖三层叠起来，叫法不严格统一，本卡用三个固定的中文称呼：

• 用户级（user / global）：跟着你这个人走，所有项目共用。位置 ~/.claude/settings.json。
• 项目级（project / shared）：跟着这个仓库走，会进 git，团队所有人共享。位置 <repo>/.claude/settings.json。
• local 级（local / personal）：跟着"你 + 这个仓库"走，默认进 .gitignore，只属于你自己这台机器。位置 <repo>/.claude/settings.local.json。

在团队 / 企业场景之上，还有一层 企业 managed settings，由 IT 推下来强制生效，普通用户不能改、也不能覆盖；放在 macOS 的 /Library/Application Support/ClaudeCode/managed-settings.json、Linux 的 /etc/claude-code/managed-settings.json、Windows 的 C:\Program Files\ClaudeCode\managed-settings.json（也支持 MDM / 注册表）。本卡聚焦个人/团队最常打交道的那三层，企业 managed 只在"覆盖优先级"那张图里提一下。

为什么要分这么多层？核心动机就一个：让"团队约定"和"个人偏好"互不打架，又能互相补强。比如团队希望所有人都禁止 curl 工具直接访问外网（写在项目级），但你个人喜欢用 iTerm2 + acceptEdits 模式跑得更顺手（写在 local），而你所有项目都希望默认显示中文（写在用户级）。三层叠起来，互相不冲突。

三层叠加的合并方向

阅读这张图的两条规则：

1. 从上往下，下面的覆盖上面的。 用户级是地板，local 级是顶（在你能改的范围里），命令行是临时插队，managed 是天花板谁都顶不动。
2. 不是整份 JSON 互相替换，而是按字段合并。 标量字段（如 model）由高优先级的那层赢；对象字段（如 env）逐键合并；数组字段（如 permissions.allow / permissions.deny）会被拼接 + 去重，不是覆盖。这一点最容易踩坑，单独抽出来在"常见误区"里讲。

核心要素

基础用法

第一步：看清三份文件分别在哪、有没有

# 用户级（全局，所有项目共用）
ls -la ~/.claude/settings.json

# 项目级（要在仓库根目录跑）
ls -la .claude/settings.json

# local 级（同样在仓库根目录）
ls -la .claude/settings.local.json

如果文件不存在很正常——Claude Code 第一次需要写入时会自动创建。.claude/settings.local.json 在被首次创建时，Claude Code 会自动把它追加到项目的 .gitignore，不需要你手动 ignore，但养成检查习惯没坏处：

grep -n "settings.local.json" .gitignore || echo "未找到，建议手动加一行 .claude/settings.local.json"

第二步：查看当前真正生效的配置

进 Claude Code 内部，输入：

/status

/status 会列出所有 settings 来源（包括是否有企业 managed），帮你确认哪一层在生效。要交互式调配置则用：

/config

/config 提供菜单式编辑，所有改动落到对应的 JSON 文件里。

第三步：典型字段配在哪一层

示例 A：用户级（所有项目通用偏好）

// ~/.claude/settings.json
{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-4-6",
  "outputStyle": "concise-zh",
  "permissions": {
    "allow": [
      "Bash(ls *)",
      "Bash(cat *)",
      "Read(~/.zshrc)"
    ],
    "defaultMode": "default"
  },
  "attribution": {
    "commit": "Co-Authored-By: Claude <[email protected]>"
  }
}

示例 B：项目级（团队共享，进 git）

// <repo>/.claude/settings.json
{
  "permissions": {
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(npm run build)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "scripts/log-bash.sh" }] }
    ]
  },
  "enabledMcpjsonServers": ["filesystem", "github"]
}

示例 C：local 级（仅你这台机器，不进 git）

// <repo>/.claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Bash(docker compose *)",
      "Read(/Volumes/external-dataset/**)"
    ],
    "defaultMode": "acceptEdits"
  },
  "env": {
    "MY_LOCAL_DEBUG_FLAG": "1"
  }
}

合并以后实际生效：

• model 取用户级的 claude-sonnet-4-6（项目和 local 都没改）。
• permissions.deny 完全保留项目级那 4 条（用户和 local 都没写 deny）。
• permissions.allow = 用户的 3 条 + 项目的 3 条 + local 的 2 条，8 条全部生效，去重之后即是结果。
• defaultMode = local 的 acceptEdits 赢（覆盖了用户级的 default）。
• env.MY_LOCAL_DEBUG_FLAG=1 生效。

同类工具对比

不同终端 Agent 都有自己的"全局 vs 项目"配置模型。理解差异有助于在多工具切换时不踩坑：

核心区别用一句话说：Claude Code 是"个人 / 团队 / 个人覆盖团队"三明治结构，且 local 层默认 gitignore；Codex 没有专门 local 层，靠 profile + -c 替代；Gemini 走"系统覆盖一切"路线，企业管控更强；Cursor 没有标量 settings 合并问题，规则全部叠加进 prompt。

迁移建议：从 Cursor 转 Claude Code 的人最容易把所有规则塞进项目级，忘了 local；从 Codex 转过来的人则容易忽略"数组合并 vs 字段覆盖"这条差异。

常见误区

优劣势分析

思考题

["Bash(npm run lint)",  // 来自用户级
 "Bash(npm run *)"]     // 来自项目级

// 项目级 deny 改为更精确的形式，给"机器人 user 名"开一个口子
{
  "permissions": {
    "deny": ["Bash(git push origin main)"],
    "allow": ["Bash(GIT_AUTHOR_NAME=release-bot git push origin main)"]
  }
}

参考资料

1. Claude Code 官方 settings 文档：https://code.claude.com/docs/en/settings（查询日期 2026-04-22）
2. Claude Code 官方 IAM / 权限文档：https://code.claude.com/docs/en/iam（查询日期 2026-04-22）
3. Claude Code GitHub Issue #18964 - settings 与 memory 优先级一致性讨论：https://github.com/anthropics/claude-code/issues/18964（查询日期 2026-04-22）
4. eesel AI - Claude Code settings.json 完整指南（2026 版）：https://www.eesel.ai/blog/settings-json-claude-code（查询日期 2026-04-22）
5. Egghead - Organizing Personal and Project Settings in Claude Code：https://egghead.io/organizing-personal-and-project-settings-in-claude-code~q7qsw（查询日期 2026-04-22）
6. Codex CLI 配置参考（用于横向对比）：https://developers.openai.com/codex/config-reference（查询日期 2026-04-22）
7. Gemini CLI 配置参考（用于横向对比）：https://geminicli.com/docs/reference/configuration/（查询日期 2026-04-22）
8. Cursor Rules 官方文档（用于横向对比）：https://cursor.com/docs/context/rules（查询日期 2026-04-22）