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 用于技术强制（比如"禁止执行 curl"），CLAUDE.md 用于行为引导（比如"提交前跑 lint"）。需要无条件拦截某个动作时用 settings 的权限规则或 hook，而不是写在 CLAUDE.md 里。

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

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

优先级从高到低（据 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.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

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

在接入外部模型服务时，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 与多模型接入配置：developer.qiniu.com/aitokenapi/13415/tools-claude-code-router-configuration-instructions