中间件 API 参考

添加于： astro@2.6.0

中间件使你能拦截请求和响应，并在每次渲染页面或端点时动态注入行为。有关功能和用法示例，请参考 中间件指南。

从 astro:middleware 导入

以下辅助函数从虚拟中间件模块导入：

import {
  defineMiddleware,
  sequence,
} from 'astro:middleware';

defineMiddleware()

类型： (fn: MiddlewareHandler) => MiddlewareHandler

一个用于定义具有类型安全的中间件函数的函数。当你使用此实用函数时，context 和 next() 参数会自动被类型化，如果你尝试返回一个 不支持的值，你将会收到 TypeScript 错误。

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  /* 你的中间件逻辑 */
});

sequence()

类型： (…handlers: MiddlewareHandler[]) => MiddlewareHandler

一个接受中间件函数作为参数的函数，它将按照它们传递的顺序执行它们。

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(context, next) {/* ... */}
async function auth(context, next) {/* ... */}
async function greeting(context, next) {/* ... */}

export const onRequest = sequence(validation, auth, greeting);

从 astro/middleware 导入

当你构建 Astro 集成 时，可以从常规中间件模块导入以下辅助函数：

import {
  createContext,
  defineMiddleware,
  sequence,
  trySerializeLocals,
} from "astro/middleware";

createContext()

类型： (context: CreateContext) => APIContext

添加于： astro@2.8.0

一个底层 API，用于创建一个 APIContext 以传递给 Astro 中间件的 onRequest() 函数。

此函数可以由集成/适配器用于以编程方式执行 Astro 中间件。

defineMiddleware()

请参考来自 astro:middleware 的 defineMiddleware()。

sequence()

请参考来自 astro:middleware 的 sequence()。

trySerializeLocals()

类型： (value: unknown) => string

添加于： astro@2.8.0

一个底层 API，它接受任何值并尝试返回它的序列化版本（一个字符串）。如果该值无法序列化，该函数将抛出一个运行时错误。

astro/middleware 类型

以下类型从常规中间件模块导入：

import type {
  CreateContext,
} from "astro/middleware";

CreateContext

类型： { request: Request; params?: Params; userDefinedLocales?: string[]; defaultLocale: string; locals: App.Locals; }

添加于： astro@2.8.0

一个用于 创建上下文 以传递给 Astro 中间件的对象。它包含以下属性：

request

类型： Request

传入的 Request 对象。

params

类型： Params

一个包含要传递给 Astro.params 的可选参数的对象。

userDefinedLocales

类型： string[]

添加于： astro@3.5.0

在 用户的 i18n 配置 中定义的支持语言环境列表。

defaultLocale

类型： string

添加于： astro@4.16.0

在 用户的 i18n 配置 中定义的默认语言环境。

locals

类型： App.Locals

添加于： astro@5.0.0

一个用于从中间件存储任意信息的对象，用户可以通过 Astro.locals 访问。

了解更多关于 在 locals 中存储数据 的示例用法。

astro 类型

import type {
  MiddlewareHandler,
  MiddlewareNext,
  RewritePayload,
} from "astro";

MiddlewareHandler

类型： (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

表示一个 Astro 中间件函数。中间件处理程序接收两个参数，可以直接返回一个 Response，或者调用 next() 来调用链中的下一个中间件。或者，你可以使用 defineMiddleware() 来为你的中间件获得类型安全。

以下示例导入 MiddlewareHandler 类型以在 onRequest() 函数中获得类型安全：

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  /* 中间件逻辑 */
};

中间件处理程序接收以下属性：

context

类型： APIContext

一个反映许多 Astro 全局属性的 Astro 上下文对象。

next()

类型： MiddlewareNext

一个调用链中所有后续中间件并返回 Response 的函数。例如，其他中间件可以修改响应的 HTML 主体，等待 next() 的结果将允许你的中间件响应这些更改。

自从 Astro v4.13.0 起，next() 接受一个可选的 URL 路径参数，形式为字符串、URL 或 Request，用于重写当前请求而不重新触发新的渲染阶段。

以下示例使用 next() 在当前路径匹配 /old-path 时提供来自不同路径的内容：

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  if (context.url.pathname === '/old-path') {
    return next('/new-path');
  }
  return next();
};

MiddlewareNext

类型： (rewritePayload?: RewritePayload) => Promise<Response>

表示传递给中间件处理程序的 next() 函数。

RewritePayload

类型： string | URL | Request

添加于： astro@4.13.0

表示传递给 next() 函数时 重写 的目标。

中间件导出

在 src/middleware.js 中定义项目的中间件时，导出以下用户定义的函数：

onRequest()

类型： MiddlewareHandler

一个在 src/middleware.js 里的必须导出的函数，它将在每次渲染页面或 API 路由时被调用。它接受两个参数：context 和 next()。onRequest() 必须返回一个 Response：要么直接返回，要么通过调用 next() 返回。

src/middleware.js

export function onRequest (context, next) {
  // 拦截一个请求的响应数据
  // 可选修改响应
  // 直接返回一个 Response 对象，或者调用 `next()` 的结果
  return next();
};