# Claude Code Prompt Cache 完全指南：原理、配置、避坑、实测省 80%

> 用 Claude Code 一段时间后最大的技术认知更新就一句话：Prompt Cache 没配好，token 账单里 80% 是冤枉付的。本文整理实战中踩过的坑、读源码和官方博客后理解的工作原理，以及一套实测有效的配置方案。

---

## 一、为什么 Claude Code 对 Prompt Cache 特别敏感

普通 LLM API 调用，输入输出大致 1:1，prompt 短，缓存收益有限。

Claude Code 的请求结构反过来——**单次请求的输入 token 远大于输出**。抓一个实际请求的 payload 看：

```
单次「修一个 bug」请求的 token 分布：
├─ system prompt（系统提示 + 24 个内置工具定义） ≈ 3,200 tokens
├─ CLAUDE.md（项目级指令）                    ≈ 800 tokens
├─ 历史消息（5 轮对话累积）                    ≈ 8,500 tokens
├─ 当前文件内容                               ≈ 2,000 tokens
└─ 用户新消息                                 ≈ 50 tokens
─────────────────────────────────────────────
输入总计：14,550 tokens
输出：≈ 400 tokens
输入/输出 比：36:1
```

**结论：Claude Code 场景下，每个输入 token 的实际单价决定总账单。**

而 Prompt Cache 提供的优惠是 **90% 折扣**——缓存命中的部分只收基础输入价的 10%。这不是"小幅优化"，是数量级差异。

---

## 二、Prompt Cache 工作原理：前缀匹配，不是"内容去重"

很多教程把 Prompt Cache 描述成"系统检测到重复内容就打折"，**这个理解是错的**。

### 2.1 真实机制：前缀完全匹配

Anthropic 服务端会保存最近发送的 prompt 前缀。下次请求时，**只要前缀（从第一个 token 开始）完全一致，就从缓存读取，跳过重新计算**。

关键约束：**前缀任何一处变化，后面所有内容的缓存全部失效。**

举例说明：

```
请求1: [Sys][Tools][CLAUDE.md v1][对话1-5][新消息A]
                                  ↓ 缓存写入
请求2: [Sys][Tools][CLAUDE.md v1][对话1-5][新消息B]
                                  ↓ 命中缓存，A 之前部分按 0.1× 计费

请求3: [Sys][Tools][CLAUDE.md v2][对话1-6][新消息C]
                          ↑ CLAUDE.md 改了一行
       从 CLAUDE.md 开始，包括对话 1-5（之前已缓存的部分）全部失效
       全部按 1.0× 重新计算 + 写入新缓存
```

### 2.2 cache_control 是怎么放的

Anthropic API 的 cache_control 标记放在 message 块上。Claude Code 的实际请求体大致长这样（精简后）：

```json
{
  "model": "claude-opus-4-7",
  "system": [
    {
      "type": "text",
      "text": "You are Claude Code...",
      "cache_control": { "type": "ephemeral" }
    }
  ],
  "tools": [...],
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<system-reminder>CLAUDE.md content...</system-reminder>",
          "cache_control": { "type": "ephemeral" }
        }
      ]
    },
    { "role": "assistant", "content": "..." },
    { "role": "user", "content": "新消息" }
  ]
}
```

注意两个 `cache_control` 标记位置——一个在 system prompt 末尾，一个在 CLAUDE.md 那条消息末尾。这意味着**有两个缓存断点（cache breakpoint）**：

- 断点 1：system + tools 是稳定层，第一次请求后整个 session 命中
- 断点 2：CLAUDE.md 是项目层，跨 session 但同项目复用

### 2.3 CLAUDE.md 不在 system prompt 里（重要细节）

读 Claude Code 的请求结构会发现一个反直觉的设计：

**CLAUDE.md 不是拼接在 system prompt 里发送的，而是通过 `<system-reminder>` XML 标签注入到 messages 数组的第一条用户消息中。**

为什么这样设计？因为 **system prompt 在所有 Claude Code 用户之间共享**——同一版本 CLI 的系统提示词字字相同。Anthropic 在服务端做了"共享前缀缓存"，所有用户共用一份 system prompt 缓存。如果把 CLAUDE.md 拼进 system prompt，每个用户的 system prompt 不一样，共享缓存就没了。

把 CLAUDE.md 单独放在 messages 中，可以独立设置 cache_control，既不破坏 system prompt 的全局共享缓存，又能让项目的 CLAUDE.md 独立缓存。

---

## 三、5min vs 1h 两档缓存：怎么选

Anthropic 提供两档 TTL 的缓存：

| 档位 | Cache Write 价格 | Cache Read 价格 | 回本条件 |
|------|----------------|----------------|---------|
| 5 分钟 | 1.25× 基础输入价 | 0.1× | 1 次命中即回本 |
| 1 小时 | 2.0× 基础输入价 | 0.1× | 2 次命中回本 |

**回本计算逻辑：**

写入溢价 = 写入价 - 1.0×（基础输入价）
节省 = 1.0× - 0.1× = 0.9×（每次命中）

- 5min 档：溢价 0.25× → 0.25 / 0.9 ≈ 0.28 次命中即回本
- 1h 档：溢价 1.0× → 1.0 / 0.9 ≈ 1.12 次命中回本

**实战选择策略：**

```
高频连续工作（< 5 分钟一次请求）→ 5min 档
任务切换或思考间隔较长（> 5min）→ 1h 档
session 跨午餐、会议等               → 1h 档
```

Claude Code 内部对 system prompt + tools 默认用 5min（高频复用），messages 部分根据时间戳和上下文自动选档。

---

## 四、5 个让缓存失效的隐藏陷阱

这部分是官方文档没明确说，但实战中最容易踩的坑。每个陷阱都能让 token 成本瞬间翻倍甚至 10 倍。

### 陷阱 1：中途修改 CLAUDE.md

最常见的坑。几轮对话后想补充一条项目规则，随手改了 CLAUDE.md：

```bash
# session 已进行 5 轮对话，缓存已建立
$ vim CLAUDE.md   # 加了一行 "用 pnpm 不用 npm"

# 继续对话
> 接着改

# 这一轮请求：CLAUDE.md 内容变了
# 从 CLAUDE.md 起的所有缓存失效
# 之前 5 轮对话的输入 token 全部按 1.0× 重新计费
```

**对策：** session 开始前规划好 CLAUDE.md，开始后只读不改。需要改时先 `/new`。

### 陷阱 2：动态时间戳/随机内容

```python
# ❌ 这种 system prompt 让缓存永远失效
SYSTEM = f"""
你是代码助手。当前时间：{datetime.now()}
请帮助用户...
"""
```

任何在前缀里塞动态内容（时间戳、随机 ID、用户名、UUID 等）都会让缓存命中率归零。每次时间戳都不同 → 前缀不同 → 缓存必然 miss。

**对策：** 动态信息放在 messages 末尾、最后一条用户消息里。前缀部分（system / tools / 早期 messages）保持稳定。

### 陷阱 3：中途切换模型

```
请求1: model=claude-opus-4-7   → 缓存写入 A
请求2: model=claude-sonnet-4-6 → 缓存 A 完全不可用，重新写入 B
```

不同模型的缓存是隔离的。中途切模型 = 抛弃当前缓存。

**对策：** 同一任务保持模型一致。需要切模型时，主动 `/new` 开新 session。

### 陷阱 4：/compact 命令的隐藏成本

`/compact` 触发的总结请求使用**专门的总结 system prompt**（不带工具定义）：

```
日常请求前缀: [Claude Code 系统提示][24 个工具定义][CLAUDE.md][对话历史]
/compact 请求: [总结 system prompt][对话历史]
                    ↑
              从第 1 个 token 就和缓存的 prefix 不同
```

整个对话历史在 `/compact` 这一次按全价计费。

**对策：**
- 不要积累几十轮再 compact，做完一个子任务就 compact 一次（被全价计费的内容更少）
- 如果只是想清空，`/new` 反而更划算（彻底清空，下次 session 重新建立缓存）

### 陷阱 5：/resume 恢复会话破坏缓存

`--resume` 或 `/resume` 在多个版本中存在缓存失效问题。恢复 session 后，前几轮请求按全价计费，导致 **10–20 倍成本暴增**。

原因是 resume 时序列化/反序列化的 messages 结构和原始结构有微小差异（额外的 metadata、空格、序列化时丢失的标记），服务端认为这是新前缀。

**对策：** 长任务尽量在一个连续 session 完成。不得不中断时，宁可在新 session 简短复述上下文，也不要 resume。

---

## 五、CLAUDE.md 最佳实践

CLAUDE.md 是缓存命中率最敏感的文件。

### 5.1 保持极简（< 50 行）

```markdown
# 项目说明

## 关键命令
- 安装: pnpm install
- 开发: pnpm dev
- 测试: pnpm test
- 部署: pnpm deploy

## 代码约定
- 用 pnpm 不用 npm
- 用 TypeScript strict 模式
- API 路由放 src/api/

## 关键文件
- 配置: config/index.ts
- 数据库 schema: prisma/schema.prisma
- 路由表: src/router.ts

## 不要做
- 不要修改 .env.production
- 不要 commit lockfile 之外的 .pnpm 目录
```

### 5.2 当作"索引"而非"文档"

CLAUDE.md 的作用是告诉 Claude **去哪里找信息**，而不是把信息塞进来。详细文档放 `docs/`，让 Claude Code 主动 Read。

### 5.3 不写动态内容

不写"今日更新""本周计划""临时方案"这类内容——会改它，缓存就会失效。

---

## 六、实测节省效果

同一个项目（中等规模 React + Node 后端，约 200 个文件），模拟典型工作流，连续提 100 个修改/重构请求：

| 场景 | 输入 token 总量 | 理论成本（按 Opus 计） |
|------|----------------|---------------------|
| 不开 Cache（强行禁用） | ≈ 1,800,000 | $9.00 |
| 默认开启 Cache（命中率 ~70%） | ≈ 540,000 等效 | $2.70 |
| 优化 CLAUDE.md + 避坑（命中率 ~92%） | ≈ 280,000 等效 | $1.40 |

**等效 token 算法：** 缓存命中部分 × 0.1 + 写入部分 × 1.25 + 未命中部分 × 1.0

优化后实测成本是不开缓存的约 **15.6%**，节省 84%。

---

## 七、配置实战，我以【灵眸AI API中专 api.lmuai.com】为例

### 7.1 settings.json 推荐配置

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https:// Authropic的官方地址或者Claude API中专地址 api.lmuai.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-..."
  },
  "effortLevel": "medium"
}
```

`effortLevel: medium` 减少推理 token 消耗（对日常代码任务质量影响很小，但能减少 20–30% token）。

### 7.2 国内开发者的实际困境与变通方案

国内无法直连 `anthropic` , 目前两种常见变通方案：

**方案 A：自建代理（Cloudflare Worker 透明转发）**

```javascript
// worker.js — 透明转发，必须保留所有 headers 和原始 body
export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = 'api.anthropic.com';
    return fetch(new Request(url, request));
  }
};
```

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的中专域名地址",
    "ANTHROPIC_AUTH_TOKEN": "sk-ant-..."
  }
}
```

**技术要点**：代理必须透明转发请求，不能修改 body，否则 `cache_control` 标记会被过滤掉，Prompt Cache 机制完全失效。这是自建代理最常见的失败原因——转发时改写了请求体。

**方案 B：可以考虑第三方 Claude API 中转服务**

部分国内 Claude API 中转服务支持官方协议透明转发，配置方式与官方 API 完全一致，例如我在用的这个：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://你的中专域名地址 api.lmuai.com",
    "ANTHROPIC_AUTH_TOKEN": "your-api-key"
  },
  "effortLevel": "medium"
}
```

选择中转服务时，**接口类型**是关键判断维度：市面上相当一部分平台走逆向接口（非官方 API），这类平台**完全不支持 Prompt Cache**——逆向接口的请求结构不包含 cache_control 字段，本文讲的所有优化技巧对这类平台无效。

**判断标准：**
1. 平台明确说明使用"官方 API 协议"而非"逆向接口"
2. 结算明细中能看到 `cache_read_input_tokens` 字段
3. 用下一节 7.3 的 curl 命令实测验证

满足以上三点的中转服务，可以完整使用本文的所有 Prompt Cache 优化技巧。

### 7.3 验证缓存是否真的命中

在 Claude Code 内查看响应中的 usage 字段，或发送以下测试请求：

```bash
curl "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: prompt-caching-2024-07-31" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-4-7",
    "max_tokens": 10,
    "system": [{"type":"text","text":"You are a helpful assistant.","cache_control":{"type":"ephemeral"}}],
    "messages": [{"role":"user","content":"hi"}]
  }' \
  -s | python3 -m json.tool
```

正常响应应包含 `usage` 字段：

```json
{
  "usage": {
    "input_tokens": 245,
    "cache_creation_input_tokens": 3120,
    "cache_read_input_tokens": 8450,
    "output_tokens": 412
  }
}
```

关注三个字段：
- `cache_creation_input_tokens`：本次写入缓存（按 1.25× 或 2.0× 计费）
- `cache_read_input_tokens`：本次缓存命中（按 0.1× 计费）
- `input_tokens`：未命中、按全价计费的部分

**诊断标准：**
- 首轮请求：`cache_creation_input_tokens` > 0，`cache_read_input_tokens` = 0（正常，建立缓存）
- 后续请求：`cache_read_input_tokens` 应远大于 `input_tokens`（缓存命中）
- 如果 `cache_creation_input_tokens` 和 `cache_read_input_tokens` 始终为 0，说明该平台不支持 Prompt Cache

### 7.4 工作节奏建议

```
开新任务   → /new （清空，建立新缓存）
连续对话   → 充分利用 Cache 命中（最便宜的状态）
做完子任务 → 趁早 /compact （被全价的内容少）
长间隔后   → 优先 /new，避免 resume
绝不中途   → 改 CLAUDE.md / 切模型 / 加时间戳
```

---

## 八、总结

Prompt Cache 是 Claude Code 单项最重要的成本机制，但官方文档没把"怎么避免缓存失效"讲清楚，导致很多人开了缓存还是花冤枉钱。

三条核心原则：

1. **保持前缀稳定** —— 不要中途改 CLAUDE.md、加时间戳、切模型
2. **同任务一气呵成** —— 长 session 比频繁 resume 更划算
3. **/compact 早用而不是攒着用** —— 越晚 compact，被全价计费的内容越多

照这三条做，配合 `effortLevel: medium` 和极简的 CLAUDE.md，token 成本可以做到不开缓存场景的 15–20%。

---

**思考题：** 如果 Claude Code 项目有多人协作，每个人的 CLAUDE.md 都不一样，团队层面有没有可能共享缓存？欢迎评论区交流。

*本文基于 Claude Code 1.x 和 Anthropic API 2026年5月文档撰写。如有错误欢迎指正。*

用 Claude Code 一段时间后最大的技术认知更新就一句话：Prompt Cache 没配好，token 账单里 80% 是冤枉付的。本文整理实战中踩过的坑、读源码和官方博客后理解的工作原理，以及一套实测有效的配置方案。

Claude Code Prompt Cache 原理、配置、避坑、实测省 80%

人工智能

开发工具

ClaudeCode的PromptCache机制能节省80%token成本，关键在于前缀匹配缓存。本文详解缓存原理、配置技巧及5大避坑指南，包括CLAUDE.md优化、缓存失效陷阱、实测节省效果等，帮助开发者最大化利用缓存机制降低API调用成本。

数据库

路由

热销域名限时优惠，新客首年免费！


domain

2026采购季 | AI焕新·智启新局

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

Claude Code Prompt Cache 原理、配置、避坑、实测省 80%-腾讯云开发者社区-腾讯云

Claude Code Prompt Cache 原理、配置、避坑、实测省 80%

Claude Code Prompt Cache 原理、配置、避坑、实测省 80%

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐