cache-bust-deploy-validation
After a production deploy of a CDN-fronted site, force cache-bust on every validation request and inspect Age/cache-status headers — the CDN can serve a stale 200 with old content for hours, hiding a broken deploy. Use whenever validating a freshly-deployed web app, debugging "deploy completed but the live site shows the old version", or building a post-deploy smoke test.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 18
- Forks
- 6
01 前言 Front Matter
- name
- cache-bust-deploy-validation
- metadata
- { "type": "skill" }
- description
- After a production deploy of a CDN-fronted site, force cache-bust on every validation request and inspect Age/cache-status headers — the CDN can serve a stale 200 with old content for hours, hiding a broken deploy. Use whenever validating a freshly-deployed web app, debugging "deploy completed but the live site shows the old version", or building a post-deploy smoke test.
02 资源文件 1
- 参考文档skill.json505 B
03 SKILL.md 正文
Cache-Bust Deploy Validation
When to use
Trigger this skill any time you are validating that a fresh deploy went live on a CDN-fronted host (Cloudflare Pages, Vercel, Netlify, Fastly, CloudFront, AWS S3+CF).
Concrete triggers:
- "Deploy completed but the live site shows the old version"
- "Validating a deploy / verifying a feature shipped"
- "Why is the new <feature> not visible?"
- Writing a post-deploy smoke test
The anti-pattern
# WRONG — the CDN happily returns 200 with cached old content
curl https://prod.example.com/page # looks fine, but is stale
A deploy can be broken at the worker but green at the edge for hours because the edge cache holds the last successful response. Validation that doesn't bypass the cache will report "all good" while real users are about to hit 404 / wrong content as soon as the cache expires.
The correct validation loop
# 1. Cache-bust on EVERY validation request
curl -sS "https://prod.example.com/page?_=$(date +%s)" -o /tmp/fresh.html
grep -c "<feature-marker>" /tmp/fresh.html # must be > 0
# 2. Inspect cache headers — Age > 60s on a path you just redeployed = stale
curl -sS -I "https://prod.example.com/page" | grep -iE 'cache|age|x-vercel|cf-'
# 3. Test the deploy preview URL too (each platform exposes one) — it
# skips the production CDN cache layer entirely.
# CF Pages: https://<deploy-hash>.<project>.pages.dev/<path>
# Vercel: URL from `vercel ls` / deployment dashboard
# Netlify: permalink under each deploy in the dashboard
Headers that signal cache masking
| Header | Meaning |
|---|---|
Age: <N> (N > 60) |
Response is N seconds old — served from cache |
cf-cache-status: HIT |
Cloudflare served from edge cache |
cf-cache-status: DYNAMIC |
NOT cached at edge (the SSR case you usually want) |
cf-cache-status: BYPASS |
CF skipped cache by config (also OK) |
x-vercel-cache: HIT |
Vercel edge cache hit |
x-cache: Hit from cloudfront |
CloudFront hit |
cache-control: no-cache, max-age=0 combined with Age: <large> |
Origin says don't cache, but something cached it anyway — investigate |
Why it matters
CDN edge caches routinely outlive deploys:
- HTML responses get cached despite
Cache-Control: no-cache(some CDNs respect onlyprivateorno-store) - Workers/Pages keep the old version until purge propagates (~30 sec to several min)
- Tiered caches mean different POPs may serve different versions for hours
- A redirect that points to a now-404 URL can be served from cache long after the breaking commit shipped
So "the site loads correctly" is not proof "the deploy worked" — it might just be proof that the cache hasn't expired.
How to purge
Use when you need users to see the new version immediately, not whenever the TTL expires.
| Platform | How |
|---|---|
| Cloudflare | Dashboard → Caching → Configuration → Purge by URL. API: POST /zones/<zone-id>/purge_cache with {"files":["https://prod/path"]} |
| Vercel | vercel rollback <prev> then redeploy, or trigger a force-redeploy commit. Vercel auto-invalidates on deploy but a stuck edge sometimes needs this. |
| Netlify | Site → Deploys → "Clear cache and deploy site" |
| Fastly | curl -X POST -H "Fastly-Key:$KEY" https://api.fastly.com/service/<service-id>/purge_all |
| CloudFront | aws cloudfront create-invalidation --distribution-id $ID --paths '/path' |
Validation script template (drop into CI smoke tests)
URL="$1"
MARKER="$2" # e.g. unique string only present in the new version
fresh=$(curl -sS "${URL}?_=$(date +%s)")
hits=$(echo "$fresh" | grep -c "$MARKER")
if [ "$hits" -lt 1 ]; then
echo "::error::Marker '$MARKER' not present in $URL — deploy may be stale or broken"
curl -sS -I "$URL" | grep -iE 'cache|age' >&2
exit 1
fi
echo "✓ Marker present, deploy live"
Anti-pattern to flag in code review
A _redirects / route rule that redirects path A → path B without first verifying that the receiving framework's worker actually has a handler at path B. Common on Astro / Next.js / Remix hybrid SSR: the framework registers routes WITHOUT a trailing slash by default; a CDN-level redirect forcing the trailing slash sends users to a path the worker doesn't serve, producing 404. The edge cache can mask this for hours before users complain.
Lessons Learned
- An add-only
_redirectsline meant to fix a perceived SEO conflict broke a section of a hybrid-SSR site for ~5h before being caught. The 5h delay was entirely due to edge cache: the production URL kept returning200withAge: ~18000s(cached pre-regression), so manual checks said "looks fine" while the actual worker was 404-ing. Lesson: every deploy validation MUST cache-bust, and a 200 with a largeAgeis a red flag, not a green one.
04 同仓库更多 Skills
yeet
Use only when the user explicitly asks to stage, commit, push, and open a GitHub pull request in one flow using the GitHub CLI (`gh`).
wrangler
Cloudflare Workers CLI for deploying, developing, and managing Workers, KV, R2, D1, Vectorize, Hyperdrive, Workers AI, Containers, Queues, Workflows, Pipelines, and Secrets Store. Load before running wrangler commands to ensure correct syntax and best practices. Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
workspace-skill-discovery
Discover and include ALL skills across the workspace — not just global ones. Use at the start of every session or when the user asks about available skills. Ensures project-level skills (under .claude/skills/ or skills/ in any repo) are never missed.
workers-best-practices
Reviews and authors Cloudflare Workers code against production best practices. Load when writing new Workers, reviewing Worker code, configuring wrangler.jsonc, or checking for common Workers anti-patterns (streaming, floating promises, global state, secrets, bindings, observability). Biases towards retrieval from Cloudflare docs over pre-trained knowledge.
winui-app
Create, build and design WinUI 3 desktop apps with C# and the Windows App SDK following Microsoft's official guidance and CommunityToolkit. Covers XAML, navigation, theming, accessibility and deployment.
windows-brain-script-portability
Scripts in ~/.claude/scripts/ that run on a Windows brain: use the python3.cmd shim and not bare python3, and reconfigure stdout to UTF-8 if you print symbols. Use it when writing a brain script or triaging a Windows-only crash.