Astro endpoint 怎样导出带缓存头的二进制响应

我在 Astro endpoint 里导出二进制内容时，最初把注意力放在“数组能不能返回”，结果真正影响下载和缓存行为的是外层的 Response。更稳妥的做法是：把 Uint8Array 作为 body，统一在 Response 的第二个参数里设置 Content-Type、下载提示和 Cache-Control。

官方地址：https://docs.astro.build/en/guides/endpoints/

Astro 文档说明，endpoint 的 GET 函数返回 Response；在 SSR 模式下，Response 还可以携带状态码和响应头。下面只讨论二进制 body 和缓存头，不展开图片编码算法。

先把 Uint8Array 变成完整 Response

endpoint 不应该把“业务层生成的字节数组”直接当成最终 HTTP 响应。先明确两层职责：Uint8Array 只表达字节内容，Response 才承载 body、状态码和 Headers。这样后面切换文件类型或缓存策略时，不需要改动字节生成逻辑。

import type { APIRoute } from "astro";

export const GET = (() => {
  // 这里模拟已经准备好的二进制内容，实际项目可来自文件或服务层。
  const bytes = Uint8Array.from([0x41, 0x73, 0x74, 0x72, 0x6f]);

  // body 放字节内容，headers 统一描述传输类型和缓存边界。
  return new Response(bytes, {
    status: 200,
    headers: {
      "Content-Type": "application/octet-stream",
      "Cache-Control": "public, max-age=60, must-revalidate",
    },
  });
}) satisfies APIRoute;

这里的关键不是数组里的示例字节，而是返回值类型。Astro endpoint 返回的是 Response，客户端拿到的 body 才会和这些 Headers 一起进入 HTTP 响应。若你的适配器或类型环境对 TypedArray body 提示不兼容，可以先使用 bytes.buffer，但要注意带有非零 byteOffset 的视图不能误把整块底层缓冲区一起发送。

Content-Type 和下载头要与用途一致

Content-Type 说明字节内容是什么，不能因为“反正都是二进制”就永远写成同一个值。确实无法确定媒体类型时，application/octet-stream 是保守选择；如果内容是 PDF、CSV 或 ZIP，则应填写对应 MIME 类型。

需要触发下载时，再增加 Content-Disposition。它和 Content-Type 不是一回事：前者影响浏览器如何处理文件，后者描述文件本身。文件名来自用户输入时，不要直接拼进响应头，应先做白名单化，避免把引号或换行带入 Header。

export const GET = (() => {
  // 示例内容代表一个已经完成序列化的导出文件。
  const bytes = new Uint8Array([0x25, 0x50, 0x44, 0x46]);

  return new Response(bytes, {
    // 成功响应使用 200，具体状态仍由 endpoint 的业务条件决定。
    status: 200,
    headers: {
      // PDF 示例；真实项目必须按实际字节格式填写。
      "Content-Type": "application/pdf",
      // 固定文件名避免把未经处理的用户输入写进 Header。
      "Content-Disposition": 'attachment; filename="report.pdf"',
    },
  });
}) satisfies APIRoute;

如果是接口调用方自己读取二进制，未必需要 attachment；如果是用户点击导出文件，加入它通常更符合预期。不要把“下载”误认为“缓存”，两者应分别由不同的 Header 控制。

缓存头怎么选，关键看数据是否公开

公开且内容短时间内稳定的文件，可以使用 public, max-age=60 这类策略；带版本号或内容哈希的静态资源，适合更长的 max-age，必要时再考虑 immutable。must-revalidate 可用于要求过期后重新向源站确认。

而用户专属、带登录态或包含敏感参数的响应，不应按公开资源缓存。可以使用 private 限制为浏览器等私有缓存；如果连私有缓存也不应保留，则使用 no-store。还要记住，no-cache 的含义是“可以存，但复用前必须重新验证”，并不等于“完全不存”。

function cacheHeaders(isPrivate: boolean): HeadersInit {
  // 个性化内容禁止进入共享缓存；公开文件才允许按时间复用。
  return isPrivate
    ? { "Cache-Control": "private, no-store" }
    : { "Cache-Control": "public, max-age=300, must-revalidate" };
}

export const GET = (({ locals }) => {
  // bytes 代表已经按业务规则生成好的二进制结果。
  const bytes = getExportBytes(locals);
  const isPrivate = Boolean(locals.user);

  return new Response(bytes, {
    // 只有 body 和缓存策略确定后，才组装最终 Response。
    headers: {
      "Content-Type": "application/octet-stream",
      ...cacheHeaders(isPrivate),
    },
  });
}) satisfies APIRoute;

上例的重点是“数据属性决定缓存策略”，不是把 public 或 no-store 当成固定模板。公开导出和个人导出最好在代码层面就有清晰分支，避免后续接入 CDN 后才发现同一个 URL 可能被不同用户复用。

静态构建与 SSR 不要混用缓存假设

静态模式下，endpoint 会在构建时生成文件；SSR 模式下，endpoint 会在请求到来时执行。两种模式的函数写法相似，但数据新鲜度完全不同：静态生成的二进制不会因为请求头改变就自动重新计算，SSR 才适合读取请求上下文并按用户或查询参数生成结果。

因此，固定内容的静态 endpoint 可以配合版本化 URL 和长缓存；请求期才生成的内容则要根据是否个性化选择 private、no-cache 或 no-store。切到 SSR 时，也要确认部署适配器确实把你设置的响应头传递出去，不能只看本地函数返回值就假设 CDN 会按同样规则工作。

遇到“能返回但缓存不对”时这样排查

1. 先确认 endpoint 最终返回的是 Response，而不是只生成了 Uint8Array。
2. 再看 Content-Type 是否与真实文件格式一致，下载场景再检查 Content-Disposition。
3. 把数据分成公开资源和个性化响应，分别审视 public、private、no-cache 与 no-store。
4. 最后确认当前是静态构建还是 SSR，以及部署适配器是否支持请求期 endpoint。

我现在会把这类问题记成一句话：Uint8Array 负责内容，Response 负责协议，Cache-Control 负责复用边界。三者分开后，二进制导出就不会再靠客户端猜测。

相关问题

Astro endpoint 可以直接返回 Uint8Array 吗？

实际接口应返回 Response，把 Uint8Array 作为 body 传入；这样才能在同一处设置状态码和响应头。

为什么设置了 max-age，用户还是拿到旧文件？

缓存会在新鲜期内复用旧响应；固定资源应使用版本化 URL 或内容哈希，动态内容则缩短新鲜时间并考虑重新验证策略。

个人文件应该用 no-cache 还是 no-store？

如果允许本地保存但每次复用前都要确认，用 no-cache；如果任何缓存都不应保存，使用 no-store。两者不是同义词。