TanStarter 文档缓存
学习如何设置和使用 Cloudflare KV 进行服务端缓存
TanStarter 使用 Cloudflare KV 进行服务端 JSON 缓存。它适合缓存读取频繁的数据，例如第三方服务状态检查、公开列表，以及可以通过短 TTL 刷新的耗时 API 响应。
Cloudflare KV 是最终一致的。请不要把 Cache 模块作为支付、认证、积分、额度或其他强一致状态的数据源。
设置
配置 Cloudflare API Token
请先完成 Cloudflare 配置，确保 Token 包含 Account > Workers KV Storage > Edit 权限。
创建 KV 命名空间
可以通过 Cloudflare 仪表盘或 Wrangler CLI 创建 KV 命名空间：
- 创建新的 KV 命名空间：
pnpm wrangler kv namespace create CACHE- 复制命令返回的
id。
- 登录 Cloudflare 仪表盘
- 导航到 Storage & Databases > KV
- 点击 Create namespace
- 输入命名空间名称，例如
CACHE - 创建完成后复制 namespace ID
配置 Wrangler 绑定
在 wrangler.jsonc 中配置 KV 命名空间绑定：
{
"kv_namespaces": [
{
"binding": "CACHE",
"id": "your-kv-namespace-id" // 注意修改这里，更改为您的 KV namespace ID
}
]
}Worker 会通过 env.CACHE 访问这个命名空间。
更新网站配置
一般情况下，保持默认配置即可，如果需要更改，可以修改 src/config/website.ts 中的 cache 配置：
export const websiteConfig = {
// ...其他配置
cache: {
enable: true,
provider: 'kv',
},
// ...其他配置
}如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。
环境配置
检查 Worker 绑定
核心功能
- 服务端 JSON 缓存辅助函数
- Cloudflare KV 提供商
- 基于 TTL 的过期时间
- 稳定的缓存 key 生成
- 单个 key 和前缀批量失效
- 缓存禁用或不可用时自动回退到原始 fetcher
使用方法
基本缓存操作
TanStarter 为常见缓存操作提供简单的 API：
import {
CACHE_TTL,
createCacheKey,
deleteCache,
getOrSetCache,
} from '@/cache';
const key = createCacheKey('newsletter:status', email);
const status = await getOrSetCache({
key,
ttlSeconds: CACHE_TTL.newsletterStatus,
fetcher: () => newsletterProvider.checkSubscribeStatus({ email }),
});
await deleteCache(key);前缀失效
列表缓存或一组相关 key 可以使用前缀失效：
import { createCacheKey, deleteCacheByPrefix } from '@/cache';
const prefix = createCacheKey('products:list');
await deleteCacheByPrefix(prefix);当前使用场景
内置的邮件订阅模块可以使用 Cache 模块缓存订阅状态检查。订阅或取消订阅成功后，会删除对应的缓存 key，下一次状态检查会重新获取最新数据。
最佳实践
- 缓存读多写少的数据：只缓存可以接受短时间过期数据的内容
- 设置清晰的 TTL：TTL 值统一放在
src/cache/constants.ts - 写入后失效缓存：数据变更后删除受影响的缓存 key
- 保持 key 稳定：使用
createCacheKey()，不要手动拼接字符串
下一步
现在您了解了如何在 TanStarter 中使用服务端缓存，探索这些相关主题：