Nuxt 3如何为生成的静态文件添加Cache-Control响应头

API 探路者

2026-8-26

问题原因

自定义中间件不生效的核心原因：

Nuxt 3 底层由Nitro驱动，.output/_nuxt路径下的构建产物由Nitro内置静态资源处理器直接响应，该逻辑优先级高于用户在server/middleware下编写的全局中间件，请求在到达自定义逻辑前就已经完成响应，头设置代码不会执行。
原有代码的Cache-Control头格式错误，max-age和s-maxage指令之间缺少逗号分隔，即便代码执行也无法被浏览器、CDN正确识别。

正确实现方案

方案1：官方routeRules配置（最简单，全环境适用）

Nuxt 3原生提供路由规则配置能力，规则优先级高于内置静态资源处理，无需编写额外中间件，直接在nuxt.config.ts中添加配置即可：

export default defineNuxtConfig({
  // 其余原有配置保持不变
  routeRules: {
    // _nuxt目录下的构建产物均带内容hash，文件变更后路径会自动更新，可安全配置一年长缓存
    '/_nuxt/**': {
      headers: {
        'Cache-Control': 'public, max-age=31536000, s-maxage=31536000, immutable'
      }
    },
    // 文件名固定、不带hash的静态资源（如public目录下的固定命名资源）按需配置短缓存即可
    '/favicon.ico': {
      headers: { 'Cache-Control': 'public, max-age=600, s-maxage=600' }
    }
  }
})

配置完成后重新执行构建/启动开发服务即可生效。

方案2：反向代理/CDN层配置（生产环境最优）

生产环境部署如果用到Nginx、CDN服务，直接在代理/CDN层配置缓存头性能最好，静态资源无需经过Node服务处理，直接由边缘节点/代理服务返回。
以Nginx配置为例：

location /_nuxt/ {
  root /your-project-path/.output/public;
  add_header Cache-Control "public, max-age=31536000, s-maxage=31536000, immutable";
  expires 1y;
}

注意事项