中间件 API 参考

添加于： astro@2.6.0

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

从 astro:middleware 导入

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

defineMiddleware()

你可以导入并使用 defineMiddleware() 工具函数来利用类型安全

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

// `context` and `next` are automatically typed
export const onRequest = defineMiddleware((context, next) => {

});

sequence()

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

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

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

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

createContext()

类型： (context: CreateContext) => APIContext

添加于： astro@2.8.0

一个用于创建APIContext的底层 API，该上下文将被传递给 Astro 中间件的 onRequest() 函数。

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

trySerializeLocals()

类型： (value: unknown) => string

添加于： astro@2.8.0

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

中间件导出

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

onRequest()

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

一个从 src/middleware.js 导出的必需函数，它将在渲染每个页面或 API 路由之前被调用。它接收两个参数：context 和 next()。onRequest() 必须返回一个 Response：可以直接返回，也可以通过调用 next() 返回。

src/middleware.js

export function onRequest (context, next) {
    // intercept response data from a request
    // optionally, transform the response
    // return a Response directly, or the result of calling `next()`
    return next();
};

你的 onRequest() 函数将使用以下参数被调用

context

类型： APIContext

onRequest() 的第一个参数是一个上下文对象。它镜像了许多 Astro 全局属性。

有关上下文对象的更多信息，请参阅端点上下文。

next()

类型： (rewritePayload?: string | URL | Request) => Promise<Response>

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

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