configure-cache-busting

适用场景

适用场景……	适合采用其他方法的场景……
为 Next.js 或 Vite 构建配置内容哈希	优化服务器端缓存（直接配置 nginx、CDN）
为 Vercel 或 Cloudflare 设置 CDN 缓存标头	调试构建输出问题（system-debugging agent）
在框架升级后验证缓存破坏机制是否符合要求	配置常规 CI/CD 工作流（/configure:workflows）
为带哈希的资源添加构建验证脚本	设置容器构建（/configure:container）
审核整个项目的静态资源缓存策略	分析前端性能（浏览器开发者工具）

上下文

• 项目根目录：!pwd
• 包文件：!find . -maxdepth 1 -name 'package.json'
• Next.js 配置：!find . -maxdepth 1 -name 'next.config.*'
• Vite 配置：!find . -maxdepth 1 -name 'vite.config.*'
• 构建输出：!find . -maxdepth 1 -type d \( -name '.next' -o -name 'dist' -o -name 'out' \)
• CDN 配置：!find . -maxdepth 2 \( -path './vercel.json' -o -path './_headers' -o -path './_redirects' -o -path './public/_headers' \)
• 项目规范：!find . -maxdepth 1 -name '.project-standards.yaml'

参数

从命令参数中解析：

• --check-only：报告合规状态，不做任何修改（CI/CD 模式）
• --fix：自动应用修复，不提示确认
• --framework <nextjs|vite>：覆盖框架检测结果
• --cdn <cloudflare|vercel|none>：指定用于缓存标头配置的 CDN 提供商

执行

执行此缓存破坏配置检查：

第 1 步：检测项目框架

根据文件结构识别框架：

指示项	框架	配置文件
next.config.js 或 next.config.mjs	Next.js	next.config.*
next.config.ts	Next.js	next.config.ts
vite.config.js 或 vite.config.ts	Vite	vite.config.*
.next/ 目录	Next.js（已构建）	仅用于检测
dist/ 目录且 package.json 中包含 vite	Vite（已构建）	仅用于检测

检查 package.json 依赖项中是否包含 "next" 或 "vite"。

如果同时检测到两者，请提示用户使用 --framework 指定框架。如果两者都未检测到，则报告不受支持并退出。

第 2 步：分析当前缓存破坏状态

对于检测到的框架，读取配置文件并检查：

Next.js - 读取 next.config.js/ts 并检查：

• 是否配置了 generateBuildId 以确保构建具有确定性
• 是否为 CDN 配置了 assetPrefix
• 是否启用了 compress: true
• 是否设置了 poweredByHeader: false 以提高安全性
• 是否配置了 generateEtags
• 是否在 headers() 函数中配置了缓存标头

Vite - 读取 vite.config.js/ts 并检查：

• build.rollupOptions.output.entryFileNames 是否使用 [hash]
• build.rollupOptions.output.chunkFileNames 是否使用 [hash]
• build.rollupOptions.output.assetFileNames 是否使用 [hash]
• 是否为基于 SSR/manifest 的路由配置了 build.manifest: true
• 是否恰当配置了 build.cssCodeSplit

第 3 步：检测 CDN 提供商

根据项目文件识别 CDN：

指示项	CDN 提供商
存在 vercel.json	Vercel
存在 .vercelignore	Vercel
根目录或 public/ 中存在 _headers	Cloudflare Pages
存在 _redirects	Cloudflare Pages / Netlify
存在 wrangler.toml	Cloudflare Workers/Pages
以上均不存在	通用 / 无

第 4 步：生成合规报告

打印格式化的合规报告：

Cache-Busting Compliance Report
================================
Project: [name]
Framework: [Next.js 14.x | Vite 5.x]
CDN Provider: [Vercel | Cloudflare | None detected]

Framework Configuration:
  Config file             next.config.js              [EXISTS | MISSING]
  Asset hashing           [hash] in filenames         [ENABLED | DISABLED]
  Build manifest          manifest files              [GENERATED | MISSING]
  Deterministic builds    Build ID configured         [PASS | NOT SET]
  Compression             gzip/brotli enabled         [PASS | DISABLED]

Cache Headers:
  Static assets           immutable, 1y               [CONFIGURED | MISSING]
  HTML files              no-cache, must-revalidate   [CONFIGURED | MISSING]
  API routes              varies by route             [CONFIGURED | N/A]
  CDN configuration       vercel.json/_headers        [EXISTS | MISSING]

Build Output (if built):
  Hashed filenames        app.[hash].js               [DETECTED | NOT BUILT]
  Content addressing      Unique hashes per version   [PASS | DUPLICATE]
  Manifest integrity      Valid manifest.json         [PASS | INVALID]

Overall: [X issues found]

Recommendations:
  [List specific fixes needed]

如果指定了 --check-only，则在此处停止。

第 5 步：应用配置（如果指定了 --fix 或用户确认）

根据检测到的框架，使用 REFERENCE.md 中的模板创建或更新配置文件：

1. Next.js：更新 next.config.js/ts，配置确定性构建、压缩和缓存标头
2. Vite：更新 vite.config.js/ts，配置内容哈希、manifest 和代码块拆分

步骤 6：配置 CDN 缓存标头

根据检测到的 CDN 提供商，使用 REFERENCE.md 中的模板创建或更新缓存标头配置：

• Vercel：创建或更新包含标头规则的 vercel.json
• Cloudflare Pages：创建包含缓存规则的 public/_headers
• 通用：提供 nginx 配置参考

步骤 7：添加构建验证

创建 scripts/verify-cache-busting.js，以验证构建后内容哈希是否生效。将构建验证脚本添加到 package.json。使用 REFERENCE.md 中的验证脚本模板。

步骤 8：配置 CI/CD 验证

在 GitHub Actions 工作流中添加缓存破坏验证步骤。使用 REFERENCE.md 中的 CI 工作流模板。

步骤 9：更新标准跟踪

更新 .project-standards.yaml：

standards_version: "2025.1"
last_configured: "[timestamp]"
components:
  cache-busting: "2025.1"
  cache-busting-framework: "[nextjs|vite]"
  cache-busting-cdn: "[vercel|cloudflare|none]"
  cache-busting-verified: true

步骤 10：打印最终报告

打印已应用的更改摘要、缓存策略概述以及后续验证步骤。

有关详细配置模板和代码示例，请参阅 REFERENCE.md。

Agentic 优化

场景	命令
快速合规检查	/configure:cache-busting --check-only
自动修复所有问题	/configure:cache-busting --fix
仅限 Next.js 项目	/configure:cache-busting --fix --framework nextjs
仅限 Vite 项目	/configure:cache-busting --fix --framework vite
Cloudflare CDN 标头	/configure:cache-busting --fix --cdn cloudflare
Vercel CDN 标头	/configure:cache-busting --fix --cdn vercel

输出

提供：

1. 包含框架和 CDN 配置状态的合规报告
2. 已进行的更改列表（如果使用 --fix）或拟议更改列表（如果采用交互模式）
3. 验证说明和命令
4. CDN 缓存标头示例
5. 部署和监控的后续步骤

另请参阅

• /configure:all - 运行所有合规检查
• /configure:status - 快速查看合规情况
• /configure:workflows - GitHub Actions 工作流标准
• /configure:dockerfile - 使用构建缓存的容器配置
• Next.js 文档 - https://nextjs.org/docs/pages/api-reference/next-config-js
• Vite 文档 - https://vitejs.dev/config/build-options.html
• Web.dev 缓存指南 - https://web.dev/http-cache/