Claude Code 配置文件怎么写：settings.json 与 CLAUDE.md 从入门到进阶

发布日期2026-07-08 | 适用读者使用 Claude Code 的开发者Claude Code 的配置由三类文件承担settings.json负责技术性配置权限、环境变量、模型、hooksCLAUDE.md负责给模型的持久化指令编码规范、项目架构、工作流.mcp.json负责 MCP 服务器接入。三者各有明确分工——settings.json 是客户端强制执行的硬约束CLAUDE.md 是引导模型行为的软指令。配置文件按作用域分为用户级~/.claude/、项目级.claude/随 git 共享、本地级.local后缀不提交和企业托管级优先级从高到低为托管 命令行 本地 项目 用户其中权限规则是跨作用域合并而非覆盖。本文基于 Claude Code 官方文档逐个拆解每类文件的位置、字段、写法与团队协作实践。一、Claude Code 有哪些配置文件Claude Code 的配置文件主要分为三类分别解决不同问题。理解它们的分工是写对配置的前提文件作用写什么是否强制执行settings.json技术配置权限、环境变量、模型、hooks是客户端强制CLAUDE.md指令记忆编码规范、项目架构、工作流否引导模型行为.mcp.jsonMCP 服务器外部工具/数据源接入—核心区别settings.json 用于技术强制比如禁止执行 curlCLAUDE.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 官方文档企业托管无法被覆盖命令行参数仅当前会话本地.claude/settings.local.json项目.claude/settings.json用户~/.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 的四条官方建议控制长度单文件建议 200 行以内过长会消耗上下文并降低遵循度具体可验证“使用 2 空格缩进胜过格式化好代码”“提交前运行npm test胜过测试你的改动”用结构化格式markdown 标题 列表分组比大段文字更易被扫描避免冲突指令两条规则矛盾时模型会随机选一条需定期清理过时内容小技巧在项目根目录运行/initClaude 会分析代码库自动生成一份起始 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 配置即可在国内直接访问统一的多模型推理入口无需改动业务代码。常见问题Qsettings.json 和 CLAUDE.md 到底有什么区别settings.json 是技术配置由客户端强制执行用于权限、环境变量、模型、hooksCLAUDE.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即使其他规则放行也会被拦截。QCLAUDE.md 写多长合适官方建议单文件控制在 200 行以内。过长会占用更多上下文并降低模型遵循度。内容多时用.claude/rules/的路径作用域规则按需加载或用path导入拆分组织注意导入文件仍会在启动时载入上下文。Qsettings.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 与多模型接入配置https://developer.qiniu.com/aitokenapi/13415/tools-claude-code-router-configuration-instructions