发布日期：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.json，CLAUDE.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_KEY
echo $ANTHROPIC_BASE_URL
echo $ANTHROPIC_MODEL

# 如果有值且与 settings.json 不一致，环境变量会胜出
# 临时清除（当前会话有效）
unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL

要永久清除，找到 Shell 配置文件中的 export ANTHROPIC_* 行并删除：

# 检查 Shell 配置文件中是否有 ANTHROPIC 相关的 export
grep -n "ANTHROPIC" ~/.zshrc ~/.bashrc ~/.bash_profile 2>/dev/null

找到对应行后用编辑器删除，然后 source ~/.zshrc（或 ~/.bashrc）重新加载。

检查点 2：JSON 语法是否合法

settings.json 是严格 JSON，不允许注释、不允许末尾逗号：

// ❌ 错误写法（有注释、末尾逗号）
{
  "apiKeyHelper": "echo $MY_KEY",  // 这是 API Key 命令
  "model": "claude-opus-4-8",      // 逗号后没有下一项
}

// ✅ 正确写法
{
  "apiKeyHelper": "echo $MY_KEY",
  "model": "claude-opus-4-8"
}

快速验证语法：

python3 -m json.tool ~/.claude/settings.json
# 语法正确时输出格式化内容，错误时显示具体行号

检查点 3：字段名大小写和拼写

Claude Code settings.json 的字段名区分大小写，常见拼写错误：

错误写法	正确写法
ApiKeyHelper	apiKeyHelper
base_url	env 里用 ANTHROPIC_BASE_URL
Model	model
maxTurns	maxTurns（驼峰，正确）

完整的 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 Code

settings.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

检查点 3：CLAUDE.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 命令

命令文件必须有 description frontmatter，否则不会出现在命令列表：

---
description: 对当前改动做代码审查，检查安全性和代码规范
---

请对以下改动进行代码审查：
1. 安全漏洞（SQL 注入、XSS、路径遍历等）
2. 代码规范违反
3. 性能问题

当前改动：$ARGUMENTS

排查步骤：

# 检查命令文件是否存在
ls ~/.claude/commands/
ls .claude/commands/   # 如果在项目里

# 检查文件是否有正确的 frontmatter
head -5 ~/.claude/commands/review.md
# 应该看到 ---  description: ...  --- 格式

# 重启 Claude Code 后再试 /help

Hooks 脚本执行权限问题

Hooks 在 settings.json 里配置，脚本文件必须有执行权限：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/format-on-save.sh"
          }
        ]
      }
    ]
  }
}

# 赋予执行权限（脚本新建后容易忘记这步）
chmod +x ~/.claude/hooks/format-on-save.sh

# 手动测试脚本是否可以独立运行
~/.claude/hooks/format-on-save.sh

Hooks 不触发的常见原因：

• 脚本没有执行权限（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-Command claude -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 里

---

常见问题 FAQ

Q1：settings.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。

Q3：CLAUDE.md 里的指令 Claude 有时遵守有时不遵守？
CLAUDE.md 是提示词，不是硬规则。如果指令模糊（“尽量简洁”），模型可能自行判断是否执行。写具体的指令（“回答不超过 3 句话”、“不添加任何注释”）比写模糊的期望更有效。另外，上下文越长，CLAUDE.md 的权重越低——长对话中期的行为漂移是正常现象，可以在提示里再次强调关键规则。

Q4：项目级 settings.json 和用户级 settings.json 同时存在时，哪个生效？
两者字段会合并，相同字段时用户级（~/.claude/settings.json）优先级高于项目级（.claude/settings.json）。例外：如果用户级没有设置某个字段，项目级的该字段生效。实践建议：model 和 env（API Key / Base URL）写用户级；permissions（权限限制）和项目约定写项目级，分层管理。

Q5：自定义命令文件改了，不重启能生效吗？
不能。命令列表在 Claude Code 启动时加载一次，修改命令文件后必须退出当前进程，重新运行 claude 才会读取新内容。如果只是修改了已有命令的提示词内容，同样需要重启。

---

小结

Claude Code 配置不生效的排查顺序：先检查环境变量是否覆盖了 settings.json（env | 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 编程教程