> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# server.staticCacheControl

- **类型：** `boolean | object`
- **默认值：** `true`

设置生产服务器返回的静态文件的 `Cache-Control` 响应头。

默认值如下：

| 文件                                                          | `Cache-Control`                       |
| ----------------------------------------------------------- | ------------------------------------- |
| 文件名包含内容哈希的构建产物，例如 `static/js/main.3f2a1b9c0d.js`            | `public, max-age=31536000, immutable` |
| 其他静态文件，例如 `config/public` 和 `config/upload` 中的文件，或不带哈希的构建产物 | `no-cache`                            |

只有位于构建产物目录（`static/` 或自定义的 JS、CSS、媒体资源 [`output.distPath`](/zh/configure/app/output/dist-path.md)）中，并且文件名包含内容哈希的文件，才会被视为带哈希的构建产物。来自 `config/public`、`config/upload` 和 `server.publicDir` 的文件始终不会被视为带哈希的构建产物。使用 `no-cache` 时，浏览器会缓存文件，但每次使用前都会向服务器确认。文件未变化时只需一次请求，不需要重新下载。

所有静态文件都会带上根据实际返回内容计算的 `ETag`。如果请求中的 `If-None-Match` 与之匹配，服务器会直接返回不带响应体的 `304 Not Modified`。文件内容来自服务器的文件缓存，返回 `304` 时不会再次从磁盘读取文件。

以上取值在生产环境中生效。开发环境中所有静态文件都使用 `no-cache`，修改后的文件不会从浏览器缓存中读取。HTML 页面不会添加该响应头，如有需要，可以通过[自定义中间件](/zh/guides/advanced-features/web-server.md)设置。

路由响应头中设置的 `Cache-Control` 或 `ETag`，以及在自定义中间件中 `await next()` 之前或之后设置的 `Cache-Control`，会优先生效。

### 自定义取值

```ts title="modern.config.ts"
export default defineConfig({
  server: {
    staticCacheControl: {
      hashed: 'public, max-age=86400',
      unhashed: 'public, max-age=300',
    },
  },
});
```

| 名称         | 类型       | 默认值                                   | 说明                        |
| ---------- | -------- | ------------------------------------- | ------------------------- |
| `hashed`   | `string` | `public, max-age=31536000, immutable` | 带哈希的构建产物的 `Cache-Control` |
| `unhashed` | `string` | `no-cache`                            | 其他静态文件的 `Cache-Control`   |

### 关闭

```ts title="modern.config.ts"
export default defineConfig({
  server: {
    staticCacheControl: false,
  },
});
```

关闭后静态文件只会带上 `ETag`，带有 `If-None-Match` 的条件请求仍然会返回 `304`。