Claude Code 配置文件怎么写：settings.json 与 CLAUDE.md 完整指南

发布日期：2026-07-08 | 适用读者：使用 Claude Code 的开发者

Claude Code 的配置由三类文件承担：settings.json 负责技术性配置（权限、环境变量、模型、hooks），CLAUDE.md 负责给模型的持久化指令（编码规范、项目架构、工作流），.mcp.json 负责 MCP 服务器接入。三者各有明确分工——settings.json 是客户端强制执行的硬约束，CLAUDE.md 是引导模型行为的软指令。配置文件按作用域分为用户级（~/.claude/）、项目级（.claude/，随 git 共享）、本地级（.local 后缀，不提交）和企业托管级，优先级从高到低为：托管 > 命令行 > 本地 > 项目 > 用户，其中权限规则是跨作用域合并而非覆盖。本文基于 Claude Code 官方文档，逐个拆解每类文件的位置、字段、写法与团队协作实践。

一、Claude Code 有哪些配置文件

Claude Code 的配置文件主要分为三类，分别解决不同问题。理解它们的分工是写对配置的前提：

文件	作用	写什么	是否强制执行
settings.json	技术配置	权限、环境变量、模型、hooks	是，客户端强制
CLAUDE.md	指令记忆	编码规范、项目架构、工作流	否，引导模型行为
.mcp.json	MCP 服务器	外部工具/数据源接入	—

核心区别：settings.json 用于技术强制（比如"禁止执行 curl"），CLAUDE.md 用于行为引导（比如"提交前跑 lint"）。需要无条件拦截某个动作时用 settings 的权限规则或 hook，而不是写在 CLAUDE.md 里。

二、settings.json 放在哪：四个作用域与优先级

settings.json 按作用域存放在不同位置，加载时按固定优先级合并。下表列出所有位置：

作用域	路径	是否共享
用户级	~/.claude/settings.json	否（个人）
项目级	.claude/settings.json	是（提交 git）
本地级	.claude/settings.local.json	否（加入 .gitignore）
企业托管	macOS /Library/Application Support/ClaudeCode/managed-settings.json 等	是（IT 部署）

优先级从高到低（据 Claude Code 官方文档）：

1. 企业托管（无法被覆盖）

2. 命令行参数（仅当前会话）

3. 本地 .claude/settings.local.json

4. 项目 .claude/settings.json

5. 用户 ~/.claude/settings.json

需要特别注意：权限规则是跨作用域"合并"而非"覆盖"，各级 allow/deny 会叠加生效。

三、settings.json 怎么写：完整示例

一个典型的 settings.json 结构如下，包含最常用的权限、环境变量与元信息字段：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "model": "claude-sonnet-5",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1"
  },
  "cleanupPeriodDays": 20
}

常用字段速查：

● model：覆盖默认模型（修改后需重启会话生效）

● permissions：权限规则（allow / deny / ask，热加载）

● env：注入所有会话的环境变量

● apiKeyHelper：生成鉴权值的 shell 命令

● hooks：生命周期事件触发的自定义命令

● cleanupPeriodDays：会话文件保留天数（默认 30）

四、权限怎么配：allow / deny / ask 三类规则

权限是 settings.json 中最常用也最关键的配置，分为三种规则，支持 * 通配符：

● allow：匹配的工具调用自动放行，例如 "Bash(npm run test *)"

● deny：匹配的工具调用始终拦截，例如 "Read(./.env)"

● ask：匹配的工具调用每次都弹窗确认，例如 "Bash(git push *)"

关键规则：deny 优先级高于 allow。当一条命令同时匹配 allow 和 deny 时，以 deny 为准，始终被拦截。这也是保护敏感文件（如 .env、secrets/）的推荐做法——把它们写进 deny，即使其他规则放行也不会泄露。

五、CLAUDE.md 怎么写：位置与有效写法

CLAUDE.md 是给模型的持久化指令文件，每次会话启动时被完整读入上下文。它同样按作用域分布：

作用域	位置	用途
用户级	~/.claude/CLAUDE.md	所有项目的个人偏好
项目级	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队共享的项目指令
本地级	./CLAUDE.local.md	个人项目偏好（加 .gitignore）
企业托管	托管策略目录下的 CLAUDE.md	组织级强制指令

写出高遵循度 CLAUDE.md 的四条官方建议：

1. 控制长度：单文件建议 200 行以内，过长会消耗上下文并降低遵循度

2. 具体可验证：“使用 2 空格缩进"胜过"格式化好代码”；“提交前运行 npm test"胜过"测试你的改动”

3. 用结构化格式：markdown 标题 + 列表分组，比大段文字更易被扫描

4. 避免冲突指令：两条规则矛盾时模型会随机选一条，需定期清理过时内容

小技巧：在项目根目录运行 /init，Claude 会分析代码库自动生成一份起始 CLAUDE.md。

六、进阶：@path 导入与 .claude/rules 路径规则

对于大型项目，可以用两种机制把配置拆分得更清晰。

@path 导入：CLAUDE.md 支持用 @path/to/file 语法导入其他文件，启动时一并加载。相对路径相对于文件自身解析，最多递归 4 层：

See @README for project overview and @package.json for available commands.
 
# 额外指令
- git 工作流 @docs/git-instructions.md

路径作用域规则：在 .claude/rules/ 放置按主题拆分的 md 文件，配合 YAML frontmatter 的 paths 字段，可让规则只在 Claude 处理匹配文件时才加载，节省上下文：

---
paths:
  - "src/api/**/*.ts"
---
 
# API 开发规则
- 所有接口必须包含入参校验
- 使用统一的错误响应格式

七、团队协作：哪些配置该提交 git

团队共享配置的关键是分清"该提交"和"不该提交"的文件，避免把个人配置或密钥混入版本库：

文件	是否提交 git	说明
.claude/settings.json	✅ 提交	团队共享的权限与规范
.claude/settings.local.json	❌ 不提交	个人本地覆盖，加 .gitignore
./CLAUDE.md / .claude/CLAUDE.md	✅ 提交	团队共享指令
CLAUDE.local.md	❌ 不提交	个人项目偏好
.mcp.json	✅ 提交	团队共用的 MCP 服务器

在接入外部模型服务时，Claude Code 兼容标准的 OpenAI SDK 与自定义网关配置，开发者可通过 env 字段或 Router 配置指向自建/第三方推理端点，例如结合七牛云的 Claude Code Router 配置，即可在国内直接访问统一的多模型推理入口，无需改动业务代码。

常见问题

Q：settings.json 和 CLAUDE.md 到底有什么区别？

settings.json 是技术配置，由客户端强制执行，用于权限、环境变量、模型、hooks；CLAUDE.md 是给模型的指令，属于软引导，用于编码规范、架构说明、工作流。需要"无论如何都拦截"的场景用 settings 的 permissions.deny 或 hook，需要"引导模型倾向某种做法"的场景写进 CLAUDE.md。

Q：项目配置和用户配置冲突了以谁为准？

按优先级：企业托管 > 命令行参数 > 本地 settings.local.json > 项目 settings.json > 用户 settings.json。高优先级覆盖低优先级。但权限规则例外——它是跨作用域合并叠加，而不是覆盖。

Q：怎么禁止 Claude 读取 .env 等敏感文件？

在 settings.json 的 permissions.deny 中加入对应模式，例如 "Read(./.env)"、"Read(./.env.*)"、"Read(./secrets/**)"。deny 优先级高于 allow，即使其他规则放行也会被拦截。

Q：CLAUDE.md 写多长合适？

官方建议单文件控制在 200 行以内。过长会占用更多上下文并降低模型遵循度。内容多时，用 .claude/rules/ 的路径作用域规则按需加载，或用 @path 导入拆分组织（注意导入文件仍会在启动时载入上下文）。

Q：settings.json 改完要重启吗？

大部分字段热加载生效，包括 permissions、hooks、apiKeyHelper；但 model、outputStyle 等字段需要重启会话才生效。

结语

Claude Code 的配置体系可以概括为一句话：用 settings.json 做技术强制，用 CLAUDE.md 做行为引导，按作用域分层管理并区分 git 提交范围。据 Claude Code 官方文档，权限规则跨作用域合并、deny 优先于 allow、CLAUDE.md 建议控制在 200 行内，是三条最容易被忽略却最影响实际效果的规则。建议团队把共享配置提交版本库、个人配置用 .local 后缀隔离，并善用 /init 生成起始文件。

本文内容基于 2026 年 7 月 Claude Code 官方文档，配置字段可能随版本更新变化，建议以官方文档最新说明为准。

延伸资源

● Claude Code Router 与多模型接入配置：通过 Router 配置 Claude Code 编程助手🪜_实用工具_AI 大模型推理 - 七牛开发者中心