TanStarter 文档缓存
学习如何设置和使用 Cloudflare KV 进行服务端缓存
TanStarter 使用 Cloudflare KV 进行服务端缓存。它适合缓存读取频繁的数据，例如第三方服务状态检查、公开列表，以及可以通过短 TTL 刷新的耗时 API 响应。
设置
配置 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 绑定
核心功能
- 服务端缓存辅助函数
- 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);最佳实践
- 缓存读多写少的数据：只缓存可以接受短时间过期数据的内容
- 设置清晰的 TTL：TTL 值统一放在
src/cache/constants.ts - 写入后失效缓存：数据变更后删除受影响的缓存 key
- 保持 key 稳定：使用
createCacheKey()，不要手动拼接字符串
下一步
现在您了解了如何在 TanStarter 中使用服务端缓存，探索这些相关主题：