缓存

缓存可以存储开销较大的操作结果（渲染后的响应、上游 API 调用、复杂计算），并在之后再次提供这些结果，而无需重新执行操作。Nitro 提供了三种使用方式：

• 缓存处理器：缓存事件处理器的完整响应。
• 缓存函数：缓存任意函数的结果，并在多个处理器之间复用。
• 路由规则：通过配置为路由模式启用缓存，而无需修改处理器代码。

#缓存处理器

要缓存事件处理器，请使用 defineCachedHandler 方法。

它的工作方式类似于 defineHandler，但多了一个用于传入缓存选项的第二个参数。

import { defineCachedHandler } from "nitro/cache";

export default defineCachedHandler((event) => {
  return "我会被缓存一小时";
}, { maxAge: 60 * 60 });

在此示例中，响应会缓存 1 小时。缓存过期后，下一个请求会等待处理器解析出新的值，然后再返回响应。如果你希望在后台重新验证时立即提供过期响应，请设置 swr: true（请参阅 SWR 行为）。

有关可用选项的更多详情，请参阅选项部分。

#处理器可以看到的内容

对于可缓存的请求，处理器接收到的请求数据，恰好就是缓存键所涵盖的数据。在处理器运行前，其他所有内容都会被移除，因此处理器无法根据缓存键无法区分的值来渲染输出，并将其存储在共享键下：

• 请求头会被剥离，除非列在 varies 中。这包括 if-none-match / if-modified-since（Nitro 会自行处理条件请求）以及 traceparent 或 x-request-id 等追踪头。
• 查询参数会被剥离，除非列在 allowQuery 中。默认情况下，/page、/page?a=1 和 /page?utm=x 都会共用一个条目，并且处理器内部的 url.searchParams 为空。
• Cookie会被剥离，除非列在 allowCookies 中，并且每个缓存响应中的 set-cookie 都会被移除。
• authorization / proxy-authorization 会被剥离，除非设置了 allowAuthorization。
• host 是唯一会被重写而非移除的请求头：它携带已解析请求源的主机名，该主机名属于缓存键的一部分。因此，为多个主机名提供服务的处理器会为每个主机名生成一个条目。

对于必须原样到达处理器的请求，请使用 shouldBypassCache。绕过缓存的请求会保留其请求头、Cookie、查询字符串和请求体，且其响应不会被存储。

#自动 HTTP 头

使用 defineCachedHandler 时，Nitro 会自动管理缓存响应上的 HTTP 缓存头：

• etag：如果处理器尚未设置，则根据响应体哈希生成弱 ETag（W/"..."）。
• cache-control：根据实际应用于条目的有效期生成，除非处理器已设置此项（请参阅下表）。
• vary：varies 中的每个名称都会合并到响应的 Vary 中；使用 allowCookies 时也会加入 Cookie。allowQuery 不会添加任何内容，因为查询参数已经包含在 URL 中。
• x-cache：类似 CDN 的缓存状态头（HIT、STALE、REVALIDATED 或 MISS）。可通过 cacheStatusHeader 选项自定义。

只有设置了 staleMaxAge 时，才会声明 stale-while-revalidate，因为该指令需要一个以秒为单位的数值。设置 swr: true 而未设置 staleMaxAge 时，过期窗口没有限制，因此下游缓存会在 max-age 之后重新验证，而 Nitro 会使用其过期副本响应。

要仅在服务器端缓存，而不向客户端和 CDN 声明 cache-control，请设置 sendCacheControl: false。

#条件请求（304 Not Modified）

缓存处理器会自动支持条件请求。当客户端发送的 if-none-match 与缓存的 etag 匹配，或者 if-modified-since 的时间等于或晚于处理器设置的 last-modified 时，Nitro 会返回不含响应体的 304 Not Modified 响应。如果两者都存在，则以 if-none-match 为准。

请求验证器会在请求被缩减范围之前捕获，因此处理器永远不会看到它们，也无法自行处理条件请求。

#可缓存的请求

只有 GET 和 HEAD 请求会被缓存。所有其他 HTTP 方法（POST、PUT、DELETE 等）都会自动绕过缓存并直接调用处理器；携带 Range 请求头的请求也会如此。

GET 和 HEAD 会使用单独的条目进行缓存，因为 HEAD 响应不包含响应体。即使使用自定义 getKey，方法仍然是缓存键的一部分。

#请求去重

当缓存正在解析时，如果有多个并发请求命中相同的缓存键，只会运行一次处理器调用。所有并发请求都会等待并共享相同的结果。

共享解析受 maxResolveTime 限制（默认 30 秒）。超时后，所有等待者都会因 TimeoutError 而被拒绝，正在刷新的条目会被移除，并且该键可以再次使用。此外，处理器还会通过 event.req.signal 收到此截止时间，因此你可以将其传递给上游 fetch 调用。

#缓存函数

你也可以使用 defineCachedFunction 缓存函数。这适用于缓存非事件处理器函数的结果，但该函数是事件处理器的一部分，并且需要在多个处理器中复用的情况。

例如，你可能想将 API 调用的结果缓存一小时：

import { defineCachedFunction } from "nitro/cache";
import { defineHandler, type H3Event } from "nitro";

export default defineHandler(async (event) => {
  const { repo } = event.context.params;
  const stars = await cachedGHStars(repo).catch(() => 0)

  return { repo, stars }
});

const cachedGHStars = defineCachedFunction(async (repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());

  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (repo: string) => repo
});

星标数会使用缓存存储（默认为内存）进行缓存。缓存键由组、名称和 getKey 的结果生成，而 value 则是星标数。

{"expires":1677851092249,"value":43991,"mtime":1677847492540,"integrity":"ZUHcsxCWEH"}

import { defineCachedFunction } from "nitro/cache";
import { defineHandler, type H3Event } from "nitro";

export default defineHandler(async (event) => {
  const { repo } = event.context.params;
  const stars = await cachedGHStars(event, repo).catch(() => 0)

  return { repo, stars }
});

const cachedGHStars = defineCachedFunction(async (event: H3Event, repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());

  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (event: H3Event, repo: string) => repo
});

#选项

defineCachedHandler 和 defineCachedFunction 函数接受以下选项：

#通用选项

以下选项可用于 defineCachedHandler 和 defineCachedFunction：

#仅适用于处理器的选项

以下选项仅适用于 defineCachedHandler：

#仅适用于函数的选项

以下选项仅适用于 defineCachedFunction：

#SWR 行为

stale-while-revalidate（SWR）模式需要通过 swr 选项显式启用（默认禁用）。了解它与其他选项的交互方式：

启用 swr 且存在已过期的缓存值时：

禁用 swr（默认）且缓存值已过期时：

#缓存键

使用 defineCachedFunction 或 defineCachedHandler 函数时，缓存键会按照以下模式生成：

`${options.base}:${options.group}:${options.name}:${options.getKey(...args)}.json`

group 和 name 在进入键之前会经过转义：移除 [A-Za-z0-9_] 之外的字符；如果值因此发生变化，则会附加原始值的哈希。这就是为什么 Nitro 的 nitro/functions 组会显示为 nitrofunctions.<hash>，并且不会与 : 键结构混淆。getKey 的结果是最后一个片段，并且会按原样存储。

例如，以下函数：

import { defineCachedFunction } from "nitro/cache";

const getAccessToken = defineCachedFunction(() => {
  return String(Date.now())
}, {
  maxAge: 10,
  name: "getAccessToken",
  getKey: () => "default"
});

将存储在类似以下的键下：

cache:nitrofunctions.3aFYDY_G88ZLdElv-hEB0r8snSViMYJ1NbRtlNP9o_0:getAccessToken:default.json

默认的 base 为 /cache，存储层会将其规范化为 cache: 前缀（与处理键中其他 / 的方式相同）。

#哪些内容会被缓存

存储响应之前，会进行以下检查。未通过任一检查的响应仍会返回给调用方，只是永远不会被存储或从缓存提供：

这些检查始终适用。使用 shouldCache 可以进一步收窄缓存范围。内置检查拒绝的响应也不会获得合成的 cache-control，因此前置 CDN 无法继续缓存错误；而被你自己的 shouldCache 拒绝的响应仍会获得该请求头。

#缓存失效

可以在运行时以编程方式使缓存条目失效（例如，在底层数据更改时通过 webhook 触发），而无需等待 maxAge 过期。

#.invalidate() 和 .expire() 方法

通过 defineCachedFunction 创建的每个函数都会公开按需重新验证方法：

• .invalidate(...args)：完全移除缓存条目。下次调用时会重新调用函数，并等待新值。
• .expire(...args)：将缓存条目标记为过期，但不移除它。启用 swr 时，仍会提供过期值，而下次调用会触发后台刷新；未启用 SWR 时，下次调用会在返回前重新解析。
• .resolveKeys(...args)：解析条目所缓存到的存储键（每个 base 前缀对应一个）。

参数会传递给 getKey，以生成缓存键。

import { defineCachedFunction } from "nitro/cache";

const cachedGHStars = defineCachedFunction(async (repo: string) => {
  const data = await fetch(`https://api.github.com/repos/${repo}`).then(res => res.json());
  return data.stargazers_count;
}, {
  maxAge: 60 * 60,
  name: "ghStars",
  getKey: (repo: string) => repo,
});

await cachedGHStars("unjs/nitro"); // populates the cache
await cachedGHStars.expire("unjs/nitro"); // marks the entry as stale
await cachedGHStars.invalidate("unjs/nitro"); // removes the entry
await cachedGHStars("unjs/nitro"); // re-invokes the function

如果没有缓存条目与给定参数匹配，.invalidate() 和 .expire() 会正常完成且不报错，并且不会更改存储。两者也会取消该键上正在进行的解析，因此清除前的值不会在清除后写入。

#缓存存储

缓存条目使用存储层存储在 cache: 前缀下（该前缀源自默认的 base: "/cache" 选项）。

默认情况下，没有为其配置专用挂载点：条目存储在根存储中，该存储使用内存驱动程序，并且在开发和生产环境中不会跨重启持久化。

要使用持久化后端，请通过 kv 选项设置 cache 挂载点：

import { defineConfig } from "nitro";

export default defineConfig({
  kv: {
    cache: {
      driver: 'redis',
      /* redis 连接器选项 */
    }
  }
})

在开发环境中，你也可以使用 $development 配置键覆盖缓存挂载点：

import { defineConfig } from "nitro";

export default defineConfig({
  kv: {
    cache: {
      // 生产环境缓存存储
    },
  },
  $development: {
    kv: {
      cache: {
        // development cache storage
      }
    }
  }
})

若要在预渲染时也覆盖它，请同时在 $prerender 中设置。

#使用路由规则

路由规则允许你直接通过配置，为匹配 glob 模式的所有路由启用缓存。对于应用中某个部分实施全局缓存策略，而无需修改处理器代码时，这尤其有用。

将所有博客路由缓存 1 小时：

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/blog/**": { cache: { maxAge: 60 * 60 } },
  },
});

cache 规则接受上文记录的相同处理器选项（swr、staleMaxAge、varies、allowQuery、allowCookies、allowAuthorization、sendCacheControl、cacheStatusHeader、stream、maxBodySize、headersOnly、base、group、name、integrity、maxResolveTime）。shouldCache 等钩子选项仅适用于 defineCachedHandler。

如果要使用自定义缓存存储挂载点，可以使用 base 选项。

import { defineConfig } from "nitro";

export default defineConfig({
  kv: {
    redis: {
      driver: "redis",
      url: "redis://localhost:6379",
    },
  },
  routeRules: {
    "/blog/**": { cache: { maxAge: 60 * 60, base: "redis" } },
  },
});

#路由规则快捷方式

你可以使用 swr 快捷方式为路由规则启用 stale-while-revalidate 缓存。swr: 3600 是 cache: { swr: true, maxAge: 3600 } 的简写。设置为 true 时，SWR 会使用默认的 maxAge 1 秒，因此建议传入明确的数值。

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/blog/**": { swr: 3600 },
    "/api/**": { swr: 60 },
  },
});

要显式禁用某个路由的缓存，请在更具体的模式上设置 cache: false（或 swr: false）。这也会移除从范围更广的模式继承的 cache 规则：

import { defineConfig } from "nitro";

export default defineConfig({
  routeRules: {
    "/api/**": { swr: 60 },
    "/api/realtime/**": { cache: false },
  },
});