Claude Code 配置后不生效？三类根因与完整排查流程

发布日期2026-06-25 | 话题AI 编程工具 | 适用人群Claude Code 用户、开发者、Windows/macOS 用户Claude Code 配置不生效的问题几乎全部落在三类根因settings.json 配置项写错或被环境变量覆盖API Key / Base URL / 模型名称填错或同名环境变量优先级更高把 JSON 配置压制了、CLAUDE.md 文件路径不对或未被加载文件放错目录、目录层级错、启动时不在项目根目录、自定义命令和 Hooks 未注册命令文件缺少必要字段、Hooks 脚本无执行权限。Claude Code 的配置优先级是固定的环境变量 用户级 settings.json 项目级 settings.jsonCLAUDE.md 的加载则依赖工作目录启动claude时的当前目录决定读哪一份项目配置。本文按三类根因逐一列出检查点和修复命令附完整的排查决策树。配置体系全貌先理解优先级动手排查之前先明确 Claude Code 的配置层级和优先级优先级高 → 低 1. 环境变量ANTHROPIC_API_KEY、ANTHROPIC_BASE_URL 等 2. 用户级 settings.json~/.claude/settings.json 3. 项目级 settings.json.claude/settings.json项目根目录最常见的陷阱在 settings.json 里改了 Base URL但 Shell 的环境变量里还有旧的ANTHROPIC_BASE_URL——环境变量优先级最高JSON 文件里的改动被静默忽略。配置文件路径速查文件路径作用范围用户级 settings~/.claude/settings.json所有项目项目级 settings项目根/.claude/settings.json当前项目全局 CLAUDE.md~/.claude/CLAUDE.md所有项目项目 CLAUDE.md项目根/CLAUDE.md或项目根/.claude/CLAUDE.md当前项目自定义命令~/.claude/commands/或.claude/commands/全局/项目第一类settings.json 配置不生效检查点 1确认没有同名环境变量覆盖# 检查是否存在会覆盖 settings.json 的环境变量echo$ANTHROPIC_API_KEYecho$ANTHROPIC_BASE_URLecho$ANTHROPIC_MODEL# 如果有值且与 settings.json 不一致环境变量会胜出# 临时清除当前会话有效unsetANTHROPIC_API_KEYunsetANTHROPIC_BASE_URL要永久清除找到 Shell 配置文件中的export ANTHROPIC_*行并删除# 检查 Shell 配置文件中是否有 ANTHROPIC 相关的 exportgrep-nANTHROPIC~/.zshrc ~/.bashrc ~/.bash_profile2/dev/null找到对应行后用编辑器删除然后source ~/.zshrc或~/.bashrc重新加载。检查点 2JSON 语法是否合法settings.json 是严格 JSON不允许注释、不允许末尾逗号// ❌ 错误写法有注释、末尾逗号 { apiKeyHelper: echo $MY_KEY, // 这是 API Key 命令 model: claude-opus-4-8, // 逗号后没有下一项 } // ✅ 正确写法 { apiKeyHelper: echo $MY_KEY, model: claude-opus-4-8 }快速验证语法python3-mjson.tool ~/.claude/settings.json# 语法正确时输出格式化内容错误时显示具体行号检查点 3字段名大小写和拼写Claude Code settings.json 的字段名区分大小写常见拼写错误错误写法正确写法ApiKeyHelperapiKeyHelperbase_urlenv里用ANTHROPIC_BASE_URLModelmodelmaxTurnsmaxTurns驼峰正确完整的 settings.json 示例国内中转配置{env:{ANTHROPIC_BASE_URL:https://你的中转地址/v1,ANTHROPIC_AUTH_TOKEN:sk-你的API Key},model:claude-opus-4-8}env字段内的键值对会作为环境变量注入 Claude Code 进程等效于在终端export但只对 Claude Code 自身有效不污染 Shell 全局环境。检查点 4修改后是否重启了 Claude Codesettings.json 在每次 Claude Code启动时读取修改后需要完全退出再重新运行claude——不是/reload是退出进程重启。第二类CLAUDE.md 不加载CLAUDE.md 是 Claude Code 的项目知识文件加载失败最常见的原因是路径不对和工作目录不匹配。检查点 1文件放对位置了吗CLAUDE.md 支持两个位置二选一方式 A项目根目录直接放 项目根/CLAUDE.md ✅ 方式 B.claude 子目录 项目根/.claude/CLAUDE.md ✅ ❌ 常见错误 项目根/claude/CLAUDE.md 目录名没有点 项目根/.claude/claude.md 文件名大小写错 项目根/.claude/agents/CLAUDE.md 放在子目录里不会自动加载检查点 2启动 claude 时的工作目录Claude Code 读取的是启动时当前目录对应的 CLAUDE.md而不是你打算操作的目录# ❌ 从家目录启动然后 cd 到项目cd~ claude# 此时读取的是 ~/.claude/CLAUDE.md全局# 不是 ~/projects/my-app/CLAUDE.md# ✅ 先进入项目目录再启动cd~/projects/my-app claude# 读取 ~/projects/my-app/CLAUDE.md 或# ~/projects/my-app/.claude/CLAUDE.md检查点 3CLAUDE.md 的多层级加载顺序Claude Code 会同时加载多个层级的 CLAUDE.md并合并内容加载顺序全部加载内容合并 1. ~/.claude/CLAUDE.md全局每次都加载 2. 项目根/CLAUDE.md 或 项目根/.claude/CLAUDE.md项目级 3. 当前工作的子目录中的 CLAUDE.md子目录级如果存在如果你在全局 CLAUDE.md 里写了某个规则但项目 CLAUDE.md 里有相反的指令两者会被同时输入给模型模型可能按较晚读取的项目级执行。需要明确在项目 CLAUDE.md 里覆写全局规则。检查点 4验证是否被加载在 Claude Code 对话里直接问列出你当前加载的所有 CLAUDE.md 文件的路径和内容摘要Claude Code 会告诉你它实际读取了哪些文件比猜测路径准确得多。第三类自定义命令和 Hooks 不工作自定义命令不出现在 /help 里自定义命令文件放在~/.claude/commands/全局或.claude/commands/项目级文件格式是 Markdown.md~/.claude/commands/ ├── review.md → 对应 /review 命令 ├── deploy.md → 对应 /deploy 命令 └── check-types.md → 对应 /check-types 命令命令文件必须有descriptionfrontmatter否则不会出现在命令列表--- description: 对当前改动做代码审查检查安全性和代码规范 --- 请对以下改动进行代码审查 1. 安全漏洞SQL 注入、XSS、路径遍历等 2. 代码规范违反 3. 性能问题 当前改动$ARGUMENTS排查步骤# 检查命令文件是否存在ls~/.claude/commands/ls.claude/commands/# 如果在项目里# 检查文件是否有正确的 frontmatterhead-5~/.claude/commands/review.md# 应该看到 --- description: ... --- 格式# 重启 Claude Code 后再试 /helpHooks 脚本执行权限问题Hooks 在 settings.json 里配置脚本文件必须有执行权限{hooks:{PostToolUse:[{matcher:Write|Edit,hooks:[{type:command,command:~/.claude/hooks/format-on-save.sh}]}]}}# 赋予执行权限脚本新建后容易忘记这步chmodx ~/.claude/hooks/format-on-save.sh# 手动测试脚本是否可以独立运行~/.claude/hooks/format-on-save.shHooks 不触发的常见原因脚本没有执行权限chmod x解决matcher字段的工具名拼写错误大小写敏感Write不是write脚本使用了相对路径Hooks 里必须用绝对路径~也可以脚本有语法错误先单独运行脚本确认能跑通特殊场景Windows 上配置不生效Windows 用户有几个额外的常见问题settings.json 路径不同Windows 路径%USERPROFILE%\.claude\settings.json 等价于C:\Users\你的用户名\.claude\settings.json 不是C:\claude\settings.json 不是C:\Users\你的用户名\settings.json用 PowerShell 确认路径# 查看路径echo$env:USERPROFILE\.claude\settings.json# 如果文件存在输出内容Get-Content$env:USERPROFILE\.claude\settings.json环境变量在 PowerShell 和系统级的区别# PowerShell 会话级关闭后消失$env:ANTHROPIC_API_KEY sk-...# 用户级永久环境变量推荐[System.Environment]::SetEnvironmentVariable(ANTHROPIC_API_KEY,sk-...,User)# 之后需要重新打开终端才能生效如果两处都有ANTHROPIC_API_KEY会话级 系统级会话级优先可能导致修改了系统级变量但不见效。claude 命令找不到PATH 问题# 确认 claude 安装位置where.exe claude# 如果没有输出手动查找Get-Commandclaude-ErrorAction SilentlyContinue# 查看 npm 全局安装路径npm config get prefix# 输出类似 C:\Users\用户名\AppData\Roaming\npm# 将 \AppData\Roaming\npm 添加到系统 PATH快速排查决策树Claude Code 配置不生效 │ ├─ API Key / Base URL 不对 / 总返回 401 │ ├─ 检查echo $ANTHROPIC_API_KEY / $ANTHROPIC_BASE_URL │ ├─ 如果有值unset 后重启 claude或删除 Shell 配置文件里的 export │ └─ 如果没值检查 settings.json 语法python3 -m json.tool 验证 │ ├─ CLAUDE.md 规则不被遵守 │ ├─ 问 Claude你加载了哪些 CLAUDE.md→ 确认路径 │ ├─ 检查启动 claude 时是否在项目根目录 │ └─ 检查文件名是否为 CLAUDE.md大写.md 后缀 │ ├─ 自定义命令 /xxx 不出现 │ ├─ 检查命令文件是否在 .claude/commands/ 目录 │ ├─ 检查文件头是否有 description frontmatter │ └─ 重启 claude 再试 │ ├─ Hooks 不触发 │ ├─ 检查chmod x 脚本文件 │ ├─ 检查matcher 字段大小写Write/Edit/Bash 首字母大写 │ └─ 单独运行脚本确认可独立执行 │ └─ Windows 特有 ├─ settings.json 路径%USERPROFILE%\.claude\settings.json ├─ 环境变量用 SetEnvironmentVariable 设置用户级重开终端 └─ claude 找不到检查 npm prefix 路径是否在 PATH 里常见问题 FAQQ1settings.json 里的env字段和 Shell 里export的环境变量有什么区别Shell 里的export是系统级环境变量对所有进程生效优先级高于 settings.json。settings.json 里的env字段只注入给 Claude Code 进程本身不影响 Shell 全局。推荐做法把 Base URL 和 API Key 写在 settings.json 的env字段里而不是 Shell 配置文件这样不同项目可以用不同配置也不会污染其他工具的环境变量。Q2改了 settings.json 但 claude 一直用旧配置重启也没用99% 的情况是 Shell 里有同名的export覆盖了 JSON 配置。运行env | grep ANTHROPIC查看当前所有 ANTHROPIC 相关变量找到后删除~/.zshrc或~/.bashrc里的对应行source ~/.zshrc重载再重启 claude。Q3CLAUDE.md 里的指令 Claude 有时遵守有时不遵守CLAUDE.md 是提示词不是硬规则。如果指令模糊“尽量简洁”模型可能自行判断是否执行。写具体的指令“回答不超过 3 句话”、“不添加任何注释”比写模糊的期望更有效。另外上下文越长CLAUDE.md 的权重越低——长对话中期的行为漂移是正常现象可以在提示里再次强调关键规则。Q4项目级 settings.json 和用户级 settings.json 同时存在时哪个生效两者字段会合并相同字段时用户级~/.claude/settings.json优先级高于项目级.claude/settings.json。例外如果用户级没有设置某个字段项目级的该字段生效。实践建议model和envAPI Key / Base URL写用户级permissions权限限制和项目约定写项目级分层管理。Q5自定义命令文件改了不重启能生效吗不能。命令列表在 Claude Code 启动时加载一次修改命令文件后必须退出当前进程重新运行claude才会读取新内容。如果只是修改了已有命令的提示词内容同样需要重启。小结Claude Code 配置不生效的排查顺序先检查环境变量是否覆盖了 settings.jsonenv | grep ANTHROPIC再检查文件路径和 JSON 语法python3 -m json.tool ~/.claude/settings.json最后确认 CLAUDE.md 是在正确工作目录下启动的直接问 Claude “你加载了哪些 CLAUDE.md”。Windows 用户额外注意 settings.json 路径%USERPROFILE%\.claude\和环境变量的用户级 vs 会话级区别。Hooks 不触发几乎都是执行权限问题chmod x。本文数据来源知乎《Claude Code 配置不生效先按这 3 类问题排查》2026-06-22、CSDN《Claude Code CLAUDE.md 不加载问题诊断报告》2026-06-09。参考来源七牛云AI 编程工具配置大全Fenno 官网AI 编程教程