configure-cache-busting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

When to Use This Skill

何时使用此技能

Use this skill when...	Use another approach when...
Configuring content hashing for Next.js or Vite builds	Optimizing server-side caching (nginx, CDN config directly)
Setting up CDN cache headers for Vercel or Cloudflare	Debugging build output issues (system-debugging agent)
Verifying cache-busting compliance after a framework upgrade	Configuring general CI/CD workflows ( `/configure:workflows` )
Adding build verification scripts for hashed assets	Setting up container builds ( `/configure:container` )
Auditing static asset caching strategy across a project	Profiling frontend performance (browser devtools)

适用场景	适用其他方案的场景
为Next.js或Vite构建配置内容哈希	优化服务器端缓存（直接配置Nginx、CDN）
为Vercel或Cloudflare设置CDN缓存头	调试构建输出问题（使用系统调试Agent）
框架升级后验证缓存击穿合规性	配置通用CI/CD工作流（ `/configure:workflows` ）
为哈希资源添加构建验证脚本	配置容器构建（ `/configure:container` ）
审计项目中静态资源的缓存策略	分析前端性能（使用浏览器开发者工具）

Context

上下文信息

Project root: !
```
pwd
```

Package files: !

find . -maxdepth 1 -name 'package.json' 2>/dev/null

Next.js config: !

find . -maxdepth 1 -name 'next.config.*' 2>/dev/null

Vite config: !

find . -maxdepth 1 -name 'vite.config.*' 2>/dev/null

Build output: !

find . -maxdepth 1 -type d \( -name '.next' -o -name 'dist' -o -name 'out' \) 2>/dev/null

CDN config: !

find . -maxdepth 1 \( -name 'vercel.json' -o -name '_headers' -o -name '_redirects' \) 2>/dev/null && find public -maxdepth 1 -name '_headers' 2>/dev/null

Project standards: !

find . -maxdepth 1 -name '.project-standards.yaml' 2>/dev/null

包文件: !

find . -maxdepth 1 -name 'package.json' 2>/dev/null

Next.js配置文件: !

find . -maxdepth 1 -name 'next.config.*' 2>/dev/null

Vite配置文件: !

find . -maxdepth 1 -name 'vite.config.*' 2>/dev/null

构建输出目录: !

find . -maxdepth 1 -type d \( -name '.next' -o -name 'dist' -o -name 'out' \) 2>/dev/null

CDN配置文件: !

find . -maxdepth 1 \( -name 'vercel.json' -o -name '_headers' -o -name '_redirects' \) 2>/dev/null && find public -maxdepth 1 -name '_headers' 2>/dev/null

项目标准文件: !

find . -maxdepth 1 -name '.project-standards.yaml' 2>/dev/null

Parameters

参数说明

Parse from command arguments:

```
--check-only
```
: Report compliance status without modifications (CI/CD mode)
```
--fix
```
: Apply fixes automatically without prompting
```
--framework <nextjs|vite>
```
: Override framework detection
```
--cdn <cloudflare|vercel|none>
```
: Specify CDN provider for cache header configuration

从命令参数中解析：

```
--check-only
```
: 仅报告合规状态，不进行修改（CI/CD模式）
```
--fix
```
: 自动应用修复，无需提示
```
--framework <nextjs|vite>
```
: 覆盖框架自动检测结果
```
--cdn <cloudflare|vercel|none>
```
: 指定用于缓存头配置的CDN提供商

Execution

执行流程

Execute this cache-busting configuration check:

执行以下缓存击穿配置检查：

Step 1: Detect project framework

步骤1：检测项目框架

Identify the framework from file structure:

Indicator	Framework	Config File
`next.config.js` or `next.config.mjs`	Next.js	`next.config.*`
`next.config.ts`	Next.js	`next.config.ts`
`vite.config.js` or `vite.config.ts`	Vite	`vite.config.*`
`.next/` directory	Next.js (built)	Detection only
`dist/` directory + vite in package.json	Vite (built)	Detection only

Check

package.json

dependencies for

"next"

"vite"

If both detected, prompt user to specify with

--framework

. If neither detected, report unsupported and exit.

通过文件结构识别框架：

识别标识	框架	配置文件
`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

指定。如果都未检测到，将报告不支持并退出。

Step 2: Analyze current cache-busting state

步骤2：分析当前缓存击穿状态

For the detected framework, read config files and check:

Next.js - Read

next.config.js/ts

and check:

```
generateBuildId
```
configured for deterministic builds
```
assetPrefix
```
configured for CDN
```
compress: true
```
enabled
```
poweredByHeader: false
```
for security
```
generateEtags
```
configured
Cache headers configured in
```
headers()
```
function

Vite - Read

vite.config.js/ts

and check:

build.rollupOptions.output.entryFileNames

uses

[hash]

build.rollupOptions.output.chunkFileNames

uses

[hash]

build.rollupOptions.output.assetFileNames

uses

[hash]

```
build.manifest: true
```
for SSR/manifest-based routing
```
build.cssCodeSplit
```
configured appropriately

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

Next.js - 读取

next.config.js/ts

并检查：

已配置
```
generateBuildId
```
以实现确定性构建
已配置
```
assetPrefix
```
用于CDN
已启用
```
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]

```
build.manifest: true
```
用于SSR/基于清单的路由
已合理配置
```
build.cssCodeSplit
```

Step 3: Detect CDN provider

步骤3：检测CDN提供商

Identify CDN from project files:

Indicator	CDN Provider
`vercel.json` exists	Vercel
`.vercelignore` exists	Vercel
`_headers` in root or `public/`	Cloudflare Pages
`_redirects` exists	Cloudflare Pages / Netlify
`wrangler.toml` exists	Cloudflare Workers/Pages
None of the above	Generic / None

通过项目文件识别CDN：

识别标识	CDN提供商
存在 `vercel.json`	Vercel
存在 `.vercelignore`	Vercel
根目录或 `public/` 下存在 `_headers`	Cloudflare Pages
存在 `_redirects`	Cloudflare Pages / Netlify
存在 `wrangler.toml`	Cloudflare Workers/Pages
以上都不存在	通用/无CDN

Step 4: Generate compliance report

步骤4：生成合规性报告

Print a formatted compliance report:

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

, stop here.

打印格式化的合规性报告：

缓存击穿合规性报告
================================
项目: [名称]
框架: [Next.js 14.x | Vite 5.x]
CDN提供商: [Vercel | Cloudflare | 未检测到]

框架配置:
  配置文件             next.config.js              [已存在 | 缺失]
  资源哈希           文件名中包含[hash]         [已启用 | 未启用]
  构建清单          清单文件              [已生成 | 缺失]
  确定性构建    已配置Build ID         [通过 | 未设置]
  压缩             已启用gzip/brotli         [通过 | 未启用]

缓存头:
  静态资源           immutable, 1y               [已配置 | 缺失]
  HTML文件              no-cache, must-revalidate   [已配置 | 缺失]
  API路由              因路由而异             [已配置 | 不适用]
  CDN配置       vercel.json/_headers        [已存在 | 缺失]

构建输出（若已构建）:
  哈希文件名        app.[hash].js               [已检测到 | 未构建]
  内容寻址      每个版本对应唯一哈希   [通过 | 重复]
  清单完整性      有效的manifest.json         [通过 | 无效]

总体情况: [发现X个问题]

建议:
  [列出需要修复的具体内容]

如果使用

--check-only

参数，在此步骤停止。

Step 5: Apply configuration (if --fix or user confirms)

步骤5：应用配置（若使用--fix或用户确认）

Based on detected framework, create or update config files using templates from REFERENCE.md:

Next.js: Update
```
next.config.js/ts
```
with deterministic builds, compression, cache headers
Vite: Update
```
vite.config.js/ts
```
with content hashing, manifest, chunk splitting

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

Next.js: 更新
```
next.config.js/ts
```
，配置确定性构建、压缩、缓存头
Vite: 更新
```
vite.config.js/ts
```
，配置内容哈希、清单、代码分割

Step 6: Configure CDN cache headers

步骤6：配置CDN缓存头

Based on detected CDN provider, create or update cache header configuration using templates from REFERENCE.md:

Vercel: Create/update
```
vercel.json
```
with header rules
Cloudflare Pages: Create
```
public/_headers
```
with cache rules
Generic: Provide nginx configuration reference

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

Vercel: 创建/更新
```
vercel.json
```
，添加头规则
Cloudflare Pages: 创建
```
public/_headers
```
，添加缓存规则
通用: 提供Nginx配置参考

Step 7: Add build verification

步骤7：添加构建验证

Create

scripts/verify-cache-busting.js

to verify content hashing works after build. Add

package.json

scripts for build verification. Use the verification script template from REFERENCE.md.

创建

scripts/verify-cache-busting.js

，用于验证构建后内容哈希是否正常工作。在

package.json

中添加构建验证脚本。使用REFERENCE.md中的验证脚本模板。

Step 8: Configure CI/CD verification

步骤8：配置CI/CD验证

Add cache-busting verification step to GitHub Actions workflow. Use the CI workflow template from REFERENCE.md.

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

Step 9: Update standards tracking

步骤9：更新标准跟踪

Update

.project-standards.yaml

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

更新

.project-standards.yaml

：

yaml

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

Step 10: Print final report

步骤10：打印最终报告

Print a summary of changes applied, cache strategy overview, and next steps for verification.

For detailed configuration templates and code examples, see REFERENCE.md.

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

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

Agentic Optimizations

Agent优化命令

Context	Command
Quick compliance check	`/configure:cache-busting --check-only`
Auto-fix all issues	`/configure:cache-busting --fix`
Next.js project only	`/configure:cache-busting --fix --framework nextjs`
Vite project only	`/configure:cache-busting --fix --framework vite`
Cloudflare CDN headers	`/configure:cache-busting --fix --cdn cloudflare`
Vercel CDN headers	`/configure:cache-busting --fix --cdn vercel`

场景	命令
快速合规性检查	`/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`

Output

输出内容

Provide:

Compliance report with framework and CDN configuration status
List of changes made (if --fix) or proposed (if interactive)
Verification instructions and commands
CDN cache header examples
Next steps for deployment and monitoring

提供：

包含框架和CDN配置状态的合规性报告
已更改的内容列表（若使用--fix）或建议的更改（若交互式）
验证说明和命令
CDN缓存头示例
部署和监控的后续步骤

另请参阅

```
/configure:all
```
- Run all compliance checks
```
/configure:status
```
- Quick compliance overview
```
/configure:workflows
```
- GitHub Actions workflow standards
```
/configure:dockerfile
```
- Container configuration with build caching
Next.js Documentation - https://nextjs.org/docs/pages/api-reference/next-config-js
Vite Documentation - https://vitejs.dev/config/build-options.html
Web.dev Caching Guide - https://web.dev/http-cache/

```
/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/

configure-cache-busting

Original

Translation

When to Use This Skill

何时使用此技能

Context

上下文信息

Parameters

参数说明

Execution

执行流程

Step 1: Detect project framework

步骤1：检测项目框架

Step 2: Analyze current cache-busting state

步骤2：分析当前缓存击穿状态

Step 3: Detect CDN provider

步骤3：检测CDN提供商

Step 4: Generate compliance report

步骤4：生成合规性报告

Step 5: Apply configuration (if --fix or user confirms)

步骤5：应用配置（若使用--fix或用户确认）

Step 6: Configure CDN cache headers

步骤6：配置CDN缓存头

Step 7: Add build verification

步骤7：添加构建验证

Step 8: Configure CI/CD verification

步骤8：配置CI/CD验证

Step 9: Update standards tracking

步骤9：更新标准跟踪

Step 10: Print final report

步骤10：打印最终报告

Agentic Optimizations

Agent优化命令

Output

输出内容

See Also

另请参阅