Middleware API Reference
本頁內容尚未翻譯。
新增於:
astro@2.6.0
Middleware allows you to intercept requests and responses and inject behaviors dynamically every time a page or endpoint is about to be rendered. For features and usage examples, see our middleware guide.
Imports from astro:middleware
Section titled Imports from astro:middlewaredefineMiddleware()
Section titled defineMiddleware()You can import and use the utility function defineMiddleware()
to take advantage of type safety:
sequence()
Section titled sequence()Type: (...handlers: MiddlewareHandler[]) => MiddlewareHandler
A function that accepts middleware functions as arguments, and will execute them in the order in which they are passed.
createContext()
Section titled createContext()Type: (context: CreateContext) => APIContext
astro@2.8.0
A low-level API to create an APIContext
to be passed to an Astro middleware onRequest()
function.
This function can be used by integrations/adapters to programmatically execute the Astro middleware.
trySerializeLocals()
Section titled trySerializeLocals()Type: (value: unknown) => string
astro@2.8.0
A low-level API that takes in any value and tries to return a serialized version (a string) of it. If the value cannot be serialized, the function will throw a runtime error.
Middleware exports
Section titled Middleware exportsWhen defining your project’s middleware in src/middleware.js
, export the following user-defined functions:
onRequest()
Section titled onRequest()Type: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void
A required exported function from src/middleware.js
that will be called before rendering every page or API route. It receives two arguments: context and next(). onRequest()
must return a Response
: either directly, or by calling next()
.
Your onRequest()
function will be called with the following arguments:
context
Section titled contextType: APIContext
The first argument of onRequest()
is a context object. It mirrors many of the Astro
global properties.
next()
Section titled next()Type: (rewritePayload?: string | URL | Request) => Promise<Response>
The second argument of onRequest()
is a function that calls all the subsequent middleware in the chain and returns a Response
. For example, other middleware could modify the HTML body of a response and awaiting the result of next()
would allow your middleware to respond to those changes.
Since Astro v4.13.0, next()
accepts an optional URL path parameter in the form of a string, URL
, or Request
to rewrite the current request without retriggering a new rendering phase.