Astro middleware 怎样把请求上下文传给页面

在 Astro 里，middleware 传递请求上下文的关键不是给页面“塞”一个全局变量，而是在 onRequest 中写入 context.locals，再由页面通过 Astro.locals 读取。这样数据只跟随当前路由渲染，既能让页面和 endpoint 共享，也不会把一次请求的数据误当成跨请求缓存。

官方文档：https://docs.astro.build/en/guides/middleware/

Astro middleware 写入 locals，页面从哪里读取

先把一个可复用的请求标识和页面提示放到 middleware。这里的数据可以来自请求头、路由参数或一次服务端查询，但示例只展示传递边界：

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  // 只把当前请求需要的字段放进 locals，避免把大对象整包传递
  const requestId = context.request.headers.get("x-request-id") ?? crypto.randomUUID();
  context.locals.requestId = requestId;
  context.locals.pageHint = context.url.pathname.startsWith("/docs") ? "文档区" : "站点首页";

  // 继续渲染当前页面，后续页面或 endpoint 才能读取这些字段
  return next();
});

页面的 frontmatter 区域直接读取 Astro.locals。它不是浏览器端脚本里的全局对象，因此这段读取发生在 Astro 服务端渲染上下文中：

---
// 读取同一请求中 middleware 已写入的值
const { requestId, pageHint } = Astro.locals;
---

当前区域：{pageHint}
请求标识：{requestId}

如果同一请求还要服务 API endpoint，思路不变：endpoint 的第一个参数也是渲染上下文，可以读取其中的 locals。因此适合放进去的是请求级、体积可控、下游确实要用的数据，不是长期状态。

类型声明和生命周期决定 locals 能做什么

TypeScript 项目不要让 locals 退化成随手拼出的对象。可以在 src/env.d.ts 为 App.Locals 声明契约，让 middleware 和页面共享字段名及类型：

type PageContext = {
  requestId: string;
  pageHint: "文档区" | "站点首页";
};

declare namespace App {
  interface Locals extends PageContext {
    // 这里的接口就是页面和 middleware 共同遵守的字段契约
    requestId: string;
    pageHint: "文档区" | "站点首页";
  }
}

这份声明解决的是编辑器提示和编译期约束，不会替你创建数据；真正的值仍要在 middleware 里按请求写入。实际判断可以用下面这张表：

官方说明里，locals 会随着一次 Astro 路由渲染结束而消失；另外，运行时整体替换 locals 可能抹掉其他中间件写入的内容，所以应当只新增或更新自己的命名空间字段。若多个 middleware 需要协作，用 sequence() 明确顺序：

import { sequence } from "astro:middleware";

const attachLocale = (context, next) => {
  // 先写入基础字段，后续 middleware 可以安全读取
  context.locals.locale = context.request.headers.get("accept-language")?.split(",")[0] ?? "zh-CN";
  return next();
};

const attachHint = (context, next) => {
  // 下游只消费已存在的 locale，不把失败变成未定义字段
  context.locals.pageHint = context.locals.locale.startsWith("zh") ? "中文内容" : "Other content";
  return next();
};

export const onRequest = sequence(attachLocale, attachHint);

常见问题

为什么页面里读不到 context.locals 写入的字段？

先确认文件是 src/middleware.ts，导出的是命名的 onRequest，并且写入后返回了 next()。若 middleware 自身抛错，页面也不会获得完整的 locals。

locals 能不能当全局缓存使用？

不适合。它绑定当前路由渲染，请求结束后就不再保留；需要跨请求复用时，使用明确的 session、数据库或缓存，并处理失效策略。

多个 middleware 会覆盖彼此的 locals 吗？

可以共享同一个 locals 对象，但应采用稳定的字段命名并用 sequence() 排序。不要把整个 locals 替换成新对象，以免清掉前面中间件已经写入的字段。

把这条链路记成一句话就够了：middleware 负责按请求准备数据，context.locals 负责在渲染链里传递，页面和 endpoint 负责消费；一旦需求跨过当前请求，就应换成真正的持久化边界。