已知问题与排错
输入“/”快速插入内容
已知问题与排错
已知问题与排错
用户1208用户12085月29日修改
本文档根据社区报告和官方通告，追踪影响 Claude Code 用户的已验证严重问题。
🚨 当前活跃严重问题
0. 提示缓存 Bug——静默费用膨胀（2026 年 3 月至今）
严重程度：🔴 高 - 成本影响状态：⚠️ 部分修复（截至 v2.1.88，Bug 3 和 Bug 2 仍活跃）Issue：#40524首次报告：2026 年 3 月受影响版本：v2.1.69+（Bug 2 & 3），v2.1.36+ 独立二进制文件（Bug 1）
问题描述
三个独立的 Bug 破坏了 Anthropic 基于前缀的提示缓存，导致产生 cache_creation 费用（全额 Token（词元）成本）而非 cache_read（折扣价）。实测的费用影响取决于使用模式：
•
单独 Bug 3（归因头）：每次会话启动和每次子智能体调用时，约 1.2 万 Token（词元）的系统提示费用膨胀 2-5 倍
•
Bug 2 激活时（恢复 + 10 个以上 Skills（技能模块））：每次恢复重建 8.7-11.8 万 Token（词元）；拥有 3-4 次恢复的会话实测缓存命中率为 4.3-34.6%（健康状态应为 95-99%），最差的会话每轮成本达到正常的 10-20 倍
•
叠加效果：应用变通方法后，缓存命中率从 48% 提升至 99.98%（社区实测，CC#40524）
依据：通过社区逆向工程（CC#40524）、泄露的 npm sourcemap 源码分析以及独立会话 JSONL 分析（ArkNill，2026 年 4 月）确认。Anthropic 在 v2.1.88 中发布了部分修复（工具 Schema 字节）。Bug 2 和 Bug 3 仍未修复。
Bug 2——--resume / --continue 时完整缓存重建（v2.1.69+）——高影响
根本原因：会话 JSONL 写入器在写入磁盘前剥离了 deferred_tools_delta 附件记录。--resume 时，这些记录已消失——因此延迟工具层没有之前的公告历史，从头重新公告所有工具。这改变了恢复对话中每条消息的位置，完全破坏了消息级别的缓存前缀。
具体证据（来自社区会话 JSONL 分析，拥有 14 个 Skills（技能模块）的会话）：
条目 | cache_read | cache_creation | 事件 |
102 | 84,164 | 174 | 正常轮次 |
103 | 0 | 87,176 | 恢复——完整重建 |
105 | 87,176 | 561 | 已恢复 |
166 | 115,989 | 221 | 正常轮次 |
167 | 0 | 118,523 | 恢复——完整重建 |
每次恢复 = 8.7-11.8 万 Token（词元）以 cache_creation 而非 cache_read 重建。每会话 3-4 次恢复 = 30-40 万个可避免的费用 Token（词元）。影响随 Skills（技能模块）/延迟工具数量线性增长：拥有 10 个以上 Skills（技能模块）的用户（框架配置中很常见）在每次恢复时都会看到 0% 的缓存命中率。
变通方法：在修复发布前避免使用 --resume 和 --continue。开启新会话。降级选项：npm install -g @anthropic-ai/claude-code@2.1.68（回归前的最后一个版本）。Anthropic 正在内部追踪此问题（在源代码遥测中标记为 inc-4747）。
工程修复：在写入会话 JSONL 时保留 deferred_tools_delta 和 mcp_instructions_delta 记录，这样恢复时就能正确计算增量，而不是重新公告所有内容。
Bug 3——归因头（低至中等影响，v2.1.69+）
根本原因：Claude Code 在每次 API 请求时将一个计费头作为系统提示的第一个块注入。该头包含一个从你第一条用户消息的字符中派生的 3 字符哈希，使其在每个会话、每个子智能体和每个附加查询中都是唯一的。由于 Anthropic 的缓存基于前缀，这个唯一的第一块在每次会话启动和子智能体调用时都会对约 1.2 万 Token（词元）的系统提示造成冷未命中。
细节（来自 jmarianski，原始逆向分析师）：每次会话系统提示的冷未命中在实践中"影响边际"，因为系统提示相对于总会话上下文而言较小。对于重度用户，恢复 Bug（Bug 2）具有更大的可测量成本。
实测：应用变通方法后，缓存命中率从 48% 提升至 99.98%——但这反映了与其他缓存因素的综合效果；单独 Bug 3 的影响可能更小。
变通方法（立即应用，风险低）：
代码块
// ~/.claude/settings.json
{
"env": {
"CLAUDE_CODE_ATTRIBUTION_HEADER": "false"
}
}
接受的值："false"、"0"、"no"、"off"。无需重启。
Bug 1——哨兵字符串替换（独立二进制 v2.1.36+，边缘情况）
根本原因：Bun 的原生 HTTP 栈在序列化后替换请求体中的 cch=00000 占位符。如果此确切字符串出现在你的消息内容中（例如，来自讨论此 Bug 的 CLAUDE.md），它可能在错误的位置被替换。
变通方法：不要在 CLAUDE.md 或配置文件中字面粘贴 cch=00000。注意：这只影响独立二进制文件，不影响 npm/npx 安装。
审计工具
运行 /check-cache-bugs（从 examples/commands 目录安装）在约 20 秒内审计你的设置是否存在所有三个 Bug。
最佳实践：在新会话开始时运行，或通过 claude -p "$(cat .claude/commands/check-cache-bugs.md)" 以单次模式运行，以避免用 cch= 字符串污染当前会话上下文（潜在的 Bug 1 触发器）。
监控缓存健康状况
要验证你的会话是否健康，使用官方的 ANTHROPIC_BASE_URL 环境变量通过本地透明代理路由，并从 API 响应中记录 cache_creation_input_tokens / cache_read_input_tokens：
代码块
// ~/.claude/settings.json
{
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:8080"
}
}