EAS Hosting 部署中的缓存

编辑页面

了解 EAS Hosting 中缓存的工作方式。

API 路由中的缓存

API 路由可以返回 Cache-Control 指令，EAS Hosting 会根据缓存指令的值适当地缓存响应。

export async function GET(request) {
  return Response.json({ ... }, {
    headers: {
	    'Cache-Control': 'public, max-age=3600'
    },
  });
}

响应中出现的 Cache-Control 指令将由 EAS Hosting 按照指定方式用于缓存响应。例如，如果 Response 指定了一个 max-age 为 1800 秒的缓存指令，那么在再次调用 API 路由之前，该响应将被缓存指定的时长。

有关 Cache-Control 指令的更多详情，请参阅 MDN 文档。

Cache-Control 指令

Cache-Control 标头既可以作为请求标头的一部分发送，也可以作为响应标头的一部分发送，并且它由以逗号分隔的一组设置组成。

当请求发送 Cache-Control 标头时，通常会发送一些指令，用于限制缓存响应可以如何被传递。如果它作为响应标头发送，它会向 EAS Hosting 指定响应将如何被缓存，以及通过重新调用 API 路由多久进行一次重新验证。

如果某个缓存指令接受参数，则该指令后面会跟一个等号和参数值，例如 max-age=3600。如果该指令不接受参数，则会在列表中不带值，例如 public。

如果传入多个缓存指令，则每个指令之间用逗号分隔，例如 public, max-age=3600。

可缓存性

若干响应指令决定缓存响应是否可以被缓存或返回给客户端：

public — 表示任何缓存（包括 EAS Hosting）都可以存储该响应。不指定它时，默认表示该响应不会在多个请求之间共享。
private — 表示该响应仅供单个用户使用，并且只能由浏览器缓存。
no-store 或 no-cache — 表示该响应绝不会被缓存或存储。

例如，指定 public, max-age=3600 表示 EAS Hosting 也被允许（此外还包括用户的浏览器）将响应存储 3600 秒。然而，private, max-age=3600 表示只有用户的浏览器可以将响应存储 3600 秒，而 EAS Hosting 不会缓存它。

对于没有设置 Authorization 标头，并且请求方法为 HEAD 或 GET 的请求，其响应会自动被视为可公开缓存。

为了区分浏览器和 EAS Hosting 可以缓存什么，可以使用 s-maxage 指令。例如，返回 s-maxage=3600 指令将允许 EAS Hosting 将响应缓存 3600 秒，而用户的浏览器则完全不会缓存它。

标头名称

如上所示，Cache-Control 标头同时被浏览器和 EAS Hosting 接受并理解。若要更细粒度地控制 EAS Hosting 的缓存，并使其与用户浏览器分开配置，你可以返回 CDN-Cache-Control 标头。使用此标头时，它会隐式地为你的指令添加 public，并强制 EAS Hosting 按照你的指令缓存响应。

export async function GET(request) {
  return Response.json({ ... }, {
    headers: {
	    'Cache-Control': 'no-store', // 浏览器不应存储该响应
	    'CDN-Cache-Control': 'max-age=3600', // EAS Hosting 应缓存 3600 秒
    },
  });
}

过期指令

max-age 用于指定一个响应在被视为过期之前会被缓存多长时间
s-maxage 用于仅向 EAS Hosting 指明它应缓存响应多长时间
no-cache 等同于指定 max-age 为零
immutable 用于指示该响应可被无限期缓存，并且应尽可能长时间地缓存，且永远不会被视为过期。

此外，还可以使用两个较新的缓存控制指令来确定当响应的 max-age 指定时间已过后，过期响应可以被使用更长时间。

stale-while-revalidate 为响应指定一个过期时间段。响应被视为过期后，它允许在指定时间范围内仍然将该响应返回给客户端，同时在后台重新验证请求。
- 例如，max-age=1800, stale-while-revalidate=3600 表示该响应会缓存 1800 秒。1800 秒后，如果对该响应发起新请求，只要请求发生在 3600 秒内，就会返回该响应，但该请求也会在后台发送到你的 API 路由。
stale-if-error 指定当底层 API 路由意外失败时，过期响应可被返回的时间段。这对于让 API 路由具备容错能力很有用，并且适用于你的 API 路由因运行时错误崩溃，或返回 500、502、503 或 504 响应状态时。
- 例如，max-age=1800, stale-if-error=3600 表示该响应会缓存 1800 秒。1800 秒后，如果你的 API 路由返回错误，则会将过期缓存响应发送给客户端，而不是错误。

请求指令

Cache-Control 标头可以作为请求标头的一部分发送，并会影响 EAS Hosting 如何选择返回缓存响应。

only-if-cached 仅在有缓存时才返回响应，否则会以 504 响应中止请求（并带有 must-revalidate 指令）
no-store、no-cache 或 max-age=0 将跳过缓存响应，并始终强制 EAS Hosting 忽略其请求缓存
min-fresh 会在缓存响应比指定值更旧时跳过该响应。例如，min-fresh=360 会阻止在缓存超过 360 秒时返回缓存响应。

此外，max-stale 和 stale-if-error 可作为请求缓存指令的一部分发送，并限制缓存响应的过期时间。然而，请记住，这并不会覆盖请求被缓存的时长，因此这只能用于减少可接受的缓存响应过期程度。

max-stale 指定客户端可接受的缓存响应的最大时间。例如，如果某个响应使用 stale-while-revalidate=3600 指令缓存，则请求可以指定 max-stale=1800，以便只接受最大过期时间为 1800 秒的过期响应（处于其过期期间，而不是 max-age 期间）
stale-if-error 可用于自定义当 API 路由原本会返回错误时，接受过期响应的时间段。

对于这两个指令，如果服务器端响应的缓存时间比在响应的 max-age 之上指定的 max-stale 或 stale-if-error 时长更短，那么这些指令将不起作用。

请求方法

除了缓存 GET 和 HEAD 请求外，EAS Hosting 也支持缓存 POST 请求。

只要发送的 POST 请求的请求体小于 1MB，你的响应就可以指定带有 public 指令的 Cache-Control 标头，以将该请求标记为可缓存。

`Expires` 标头

EAS Hosting 也支持使用较旧的 Expires 标头进行缓存。

由于这不会将响应标记为可公开缓存，因此它通常仅用于未认证的 GET 响应。它可以指定一个 HTTP Date 值，直到响应被缓存。到达指定时间戳后，该响应将被视为过期。

`Vary` 标头

默认情况下：

GET 或 HEAD 请求只按其 URL 缓存
POST 请求只按其 URL 和请求体缓存

不过，你可以使用 Vary 标头来指定请求应使用请求标头作为缓存键。例如，如果某个 API 路由响应 Vary: custom-header ，那么只有当请求的 custom-header 标头值与缓存请求的 custom-header 值匹配时，才会使用该缓存响应。

CORS 缓存

对于许多 Web 请求，浏览器会使用 OPTIONS 方法发起 CORS 请求，以确定某条路由的访问控制设置。

这些请求可以使用特殊的 Access-Control-Max-Age 标头进行缓存。例如，Access-Control-Max-Age: 3600 会将 OPTIONS 响应缓存 3600 秒，这同时适用于浏览器和 EAS Hosting 缓存。这可以防止浏览器发出过多请求，并防止你的 API 路由因 CORS 请求而被过于频繁地调用。

资源缓存

对于部署返回的任何资源，浏览器缓存将默认应用 3600 秒的缓存时间。为了提升性能，按部署划分的资源会在内部被无限期缓存。由于部署是不可变的，这不会影响你。

当你将新部署分配给某个别名时，EAS Hosting 会忽略其缓存的资源。例如，当你将新部署提升到生产环境时，缓存将被忽略，你的资源响应应会立即切换到新的部署。

计费与指标

EAS Hosting 按请求计费（按 100 万请求为单位）。然而，缓存请求仍然计入你的配额，即使这些请求被 EAS Hosting 缓存，你也仍会被收费。

指标不受缓存影响。缓存请求会像其他任何请求一样被记录，EAS 仪表板中的指标也会反映并体现缓存请求。