Vercel缓存问题排查
针对 Vercel 上内容不更新、命中率偏低或 ISR 成本异常,用 CLI 指标与请求日志定位到具体缓存层和 cacheReason 并给处置建议。
功能与用途
专门用于排查和优化 Vercel 平台 CDN 缓存问题的实操指南。覆盖 Vercel 分层缓存架构(CDN 缓存、ISR 缓存、函数执行及图片缓存)的工作原理,指导开发者利用 vercel metrics 查看指标、按 cache_result 分组计算真实命中率,并结合 x-vercel-cache 响应头与 9 种 cacheReason(如 cold、collapsed、stale_time 等)精准定位 MISS、STALE 或 BYPASS 的根因。同时深入对比 invalidate(软失效)与 dan
适用场景
- 后台改了商品价格但前台还是旧价格,怀疑是缓存没刷掉,但不知道:后台改了商品价格但前台还是旧价格,怀疑是缓存没刷掉,但不知道是标签问题还是重新验证失败
- 账单里 ISR 的读写单元这个月翻了一倍,想找出是哪些路径在:账单里 ISR 的读写单元这个月翻了一倍,想找出是哪些路径在反复触发重新生成
- 整体缓存命中率只有六成,需要弄清楚 MISS 是集中在少数几:整体缓存命中率只有六成,需要弄清楚 MISS 是集中在少数几条路由上还是普遍存在
适用人群
- Vercel 部署的网站运维工程师
- 负责 Next.js 上线性能的前端工程师
- 管理云成本的独立开发者
使用步骤
- 说明项目所在的团队和项目名,以及具体症状——命中率低、内容不更新、成本异常还是某个请求没走缓存。
- 它先用 vercel metrics 按 cache_result 分组看整体情况,剔除 BYPASS 和 (not set) 后算出真实的缓存命中率。
- 它再按路径类型和具体路由定位 MISS 集中位置,并用 vercel logs 读出问题请求的 cacheReason。
- 根据结论处置:改用细粒度标签加汇总标签、把硬删除换成保持旧内容后台刷新,或修掉重新验证失败的问题。
开始使用
将需求和 Skill 名称发送给已连接 SkillPX MCP 的 AI 助手,核对适用工具和安装要求。
技术信息
- 分类
- IT运维与安全
- 适用工具
- Codex、Claude Code、OpenClaw、Hermes、国内 Agent
- 使用难度
- 专业
- 版本
- main
- 最近更新
- 2026-09-18
- 文件数
- 3
- 安装包大小
- 自动生成 ZIP
- 安全检查
- 基础检查通过
Debug Vercel CDN caching — cache hit rate, stale content, revalidation behavior, ISR + PPR, per-request cache reasons (cacheReason), and costs.
使用前准备
- 需要 Vercel CLI 并完成登录、知道团队与项目名
- 聚合指标需开通 Observability Plus,定位问题需熟悉分层缓存与 ISR/PPR 机制
依赖与权限
- 读取用户主动提供的内容