+ +**类型：** `string` +
+ +为你的适配器定义一个唯一的名称。这将用于日志记录。 + +### `serverEntrypoint` + ++ +**类型：** `string | URL` +
+ +定义按需渲染的入口点。 + +
+
+**类型：** `AstroAdapterFeatureMap`
+
+
+**类型：** `AstroAdapterFeatures`
+
+ +**类型：** `any` +
+ +一个 JSON 可序列化的值，将在运行时传递给适配器的服务器入口点。这对于将包含构建时配置（例如路径、密钥）的对象传递给服务器运行时代码非常有用。 + +以下示例定义了一个 `args` 对象，其中包含一个属性，用于标识 Astro 生成的资源所在的位置： + + +```js title="my-adapter.mjs" {9-11} +export default function createIntegration() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ config, setAdapter }) => { + setAdapter({ + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', + args: { + assets: config.build.assets + } + }); + }, + }, + }; } +``` + +### `client` -export interface AstroAdapterFeatures { - /** - * 创建一个与 Astro 中间件通信的边缘函数 - */ - edgeMiddleware: boolean; - /** - * 确定适配器的构建输出类型。默认为 `server`。 - */ - buildOutput?: 'static' | 'server'; +
+
+**类型：** `{ internalFetchHeaders?: Record
+
+
+**类型：** `Record
-export type AdapterSupport = AdapterSupportsKind | AdapterSupportWithMessage; - -export type AstroAdapterFeatureMap = { - /** - * 适配器对静态页面的支持 - */ - staticOutput?: AdapterSupport; - /** - * 适配器对静态页面或通过服务器渲染的页面的支持 - */ - hybridOutput?: AdapterSupport; - /** - * 适配器对按需渲染的支持 - */ - serverOutput?: AdapterSupport; - /** - * 适配器对 i18n 域名的支持 - */ - i18nDomains?: AdapterSupport; - /** - * 适配器对 `astro:env/server` 导出的 `getSecret` 的支持 - */ - envGetSecret?: AdapterSupport; - /** - * 适配器对 Sharp 图像服务的支持 - */ - sharpImageService?: AdapterSupport; -}; +**类型：** `URLSearchParams` +
+ +定义要追加到所有资源 URL （例如图片、样式表、脚本）的查询参数。这对于需要跟踪部署版本或其他元数据的适配器非常有用。 +以下示例从环境变量中检索 `DEPLOY_ID`，如果提供了该变量，则返回一个对象，其中自定义搜索参数名称作为键，部署 ID 作为值： + +```js title="my-adapter.mjs" {9-13} +export default function createIntegration() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ config, setAdapter }) => { + setAdapter({ + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', + client: { + assetQueryParams: process.env.DEPLOY_ID + ? new URLSearchParams({ yourParam: process.env.DEPLOY_ID }) + : undefined, + }, + }); + }, + }, + }; +} ``` -这些属性分别是： +### `exports` + ++ +**类型：** `string[]` +
+ +定义一个命名导出数组，与服务器入口点的 [`createExports()` 函数](#createexports) 配合使用。 + +以下示例假设 `createExports()` 提供了一个名为 `handler` 的导出： -* __name__：适配器的唯一名称，用于日志记录。 -* __serverEntrypoint__：按需服务器渲染的入口。 -* __exports__：导出数组，与 `createExports` 配套使用（在下文中说明）。 -* __adapterFeatures__：一个对象，用于启用适配器必须支持的特定功能。这些功能将改变构建输出，适配器必须实现适当的逻辑来处理不同的输出。 -* __supportedAstroFeatures__：Astro 内置功能的映射。这允许 Astro 确定适配器无法或不愿意支持的功能，以便提供适当的错误消息。 +```js title="my-adapter.mjs" {9} +export default function createIntegration() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ config, setAdapter }) => { + setAdapter({ + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', + exports: ['handler'] + }); + }, + }, + }; +} +``` -### 服务端入口 +### `previewEntrypoint` -Astro 的适配器 API 尝试适配多种类型的托管方，并提供了灵活的配置方式。 +
-#### Exports
+**类型：** `string | URL`
+
+
+**类型：** (manifest: SSRManifest, options: any) => Record\
+
+
+**类型：** (manifest: SSRManifest, options: any) => Record\
+
**类型：** `(request: Request, options?: RenderOptions) => Promise
@@ -293,22 +453,23 @@ try {
以下示例读取了磁盘中的 `500.html` 和 `404.html`，而不是执行 HTTP 调用：
-```js "prerenderedErrorPageFetch"
+```ts "prerenderedErrorPageFetch"
return app.render(request, {
prerenderedErrorPageFetch: async (url: string): Promise
-**类型：** `RouteData`
-**类型：** `(request: Request) => RouteData | undefined`
+**类型：** `(request: Request, allowPrerenderedRoutes = false) => RouteData | undefined`
+
+**类型：** `() => AstroIntegrationLogger`
-
+**类型：** [`RouteData`](/zh-cn/reference/integrations-reference/#routedata)
**默认值：** `app.match(request)`
+
+
-以下配置告诉 Astro，该适配器对 Sharp 提供的内置图像服务有实验性支持：
+**类型：** `(pathname: string) => string`
+
+
+**类型：** `(response: Response) => Generator
+
-[@example/my-adapter] The currently selected adapter `@example/my-adapter` is not compatible with the service "Sharp". Your project will NOT be able to build.
-```
+**类型：** `(response: Response) => Generator
+
-**类型：** `'default' | 'all'`
-
+
+
+**类型：** `(hostname: string | undefined) => string | undefined`
+
-### `edgeMiddleware`
+**类型：** `(forwardedProtocol?: string, forwardedHost?: string, forwardedPort?: string, allowedDomains?: Partial
+
-**类型：** `boolean`
+**类型：** `(request: NodeRequest | Request, options?: RenderOptions) => Promise
+
+ +**类型：** `(req: NodeRequest | Request, allowPrerenderedRoutes?: boolean) => RouteData | undefined` +
+ +扩展 [`app.match()`](#appmatch)，除了标准的 `Request` 对象外，还可以接受 [Node.js `IncomingMessage`](https://nodejs.org/api/http.html#class-httpincomingmessage) 对象。 + +```js +if(nodeApp.match(request)) { + const response = await nodeApp.render(request); +} +``` + +#### `nodeApp.headersMap` + +
+
+**类型：** `NodeAppHeadersJson | undefined`
+**默认值：** `undefined`
+
+
+**类型：** `(headers: NodeAppHeadersJson) => void`
+
+
+**类型：** `(req: NodeRequest, options?: { skipBody?: boolean; allowedDomains?: Partial
+
+
+**类型：** `(source: Response, destination: ServerResponse) => Promise
+
-**类型：** `AdapterSupportsKind` +**类型：** [`AdapterSupport`](#adaptersupport)
-此功能允许你的适配器获取用户在 `env.schema` 中配置的密钥。 +定义适配器是否能够提供静态页面。 -通过任何有效的 `AdapterSupportsKind` 值传递给适配器来启用此功能： +### `hybridOutput` + ++ +**类型：** [`AdapterSupport`](#adaptersupport) +
+ +定义适配器是否能够提供包含静态和按需渲染页面混合的站点。 + +### `serverOutput` + ++ +**类型：** [`AdapterSupport`](#adaptersupport) +
+ +定义适配器是否能够提供按需渲染的页面。 + +### `i18nDomains` + +
+
+**类型：** [`AdapterSupport`](#adaptersupport)
+
+
+**类型：** [`AdapterSupport`](#adaptersupport)
+
-**类型：** `'static' | 'server'`
+**类型：** [`AdapterSupport`](#adaptersupport)
+ +**类型：** `boolean` +
+ +定义构建时是否将打包任何按需渲染的中间件代码。 + +启用后，这会阻止中间件代码在构建期间被所有页面打包和导入： ```js title="my-adapter.mjs" ins={9-11} export default function createIntegration() { @@ -652,28 +1001,86 @@ export default function createIntegration() { name: '@example/my-adapter', serverEntrypoint: '@example/my-adapter/server.js', adapterFeatures: { - buildOutput: 'static' + edgeMiddleware: true + } + }); + }, + }, + }; +} +``` + +然后，使用钩子 [`astro:build:ssr`](/zh-cn/reference/integrations-reference/#astrobuildssr)，它将给你一个 `middlewareEntryPoint`，即文件系统上物理文件的 `URL`。 + +```js title="my-adapter.mjs" ins={15-20} +export default function createIntegration() { + return { + name: '@example/my-adapter', + hooks: { + 'astro:config:done': ({ setAdapter }) => { + setAdapter({ + name: '@example/my-adapter', + serverEntrypoint: '@example/my-adapter/server.js', + adapterFeatures: { + edgeMiddleware: true } }); }, + + 'astro:build:ssr': ({ middlewareEntryPoint }) => { + // 记得检查此属性是否存在，如果适配器未选择使用该功能，它将返回 `undefined` + if (middlewareEntryPoint) { + createEdgeMiddleware(middlewareEntryPoint) + } + } }, }; } + +function createEdgeMiddleware(middlewareEntryPoint) { + // 使用你的打包器发出一个新的物理文件 +} ``` -### experimentalStaticHeaders +### `buildOutput`
-**类型：** `true | false`
-
+**默认值：** `"server"`
+
-例如，当启用 CSP（内容安全策略）时，`` 元素不会被添加至静态页面。取而代之的是，其 `content` 可在 `experimentalRouteToHeaders` 映射中获取。
+**类型：** `boolean`
+
+
+**类型：** AdapterSupportsKind | AdapterSupportWithMessage
+
+ +**类型：** `"deprecated" | "experimental" | "limited" | "stable" | "unsupported"` +
+ +定义适配器对特性的支持级别： +* 当你的适配器在未来版本中完全移除某个特性之前弃用对该特性的支持时，使用 `"deprecated"`。 +* 当你的适配器添加了对某个特性的支持，但预计会出现问题或重大更改时，使用 `"experimental"`。 +* 当你的适配器仅支持完整特性的子集时，使用 `"limited"`。 +* 当你的适配器完全支持该特性时，使用 `"stable"`。 +* 使用 `"unsupported"` 警告用户他们的项目可能会遇到构建问题，因为你的适配器不支持此特性。 + +### `AdapterSupportWithMessage` + +
+
+
+
+**类型：** Exclude\<AdapterSupportsKind, "stable"\>
+
+ +**类型：** `string` +
+ +定义关于适配器对特性支持的自定义消息。 + +#### `suppress` + +
+
+**类型：** `"default" | "all"`
+
-**类型：** `(renderer:` [`AstroRenderer`](https://github.com/withastro/astro/blob/fdd607c5755034edf262e7b275732519328a33b2/packages/astro/src/%40types/astro.ts#L872-L883) `) => void;`
+**类型：** (renderer: AstroRenderer) => void;
**示例：** [`svelte`](https://github.com/withastro/astro/blob/main/packages/integrations/svelte/src/index.ts)、[`react`](https://github.com/withastro/astro/blob/main/packages/integrations/react/src/index.ts)、[`preact`](https://github.com/withastro/astro/blob/main/packages/integrations/preact/src/index.ts)、[`vue`](https://github.com/withastro/astro/blob/main/packages/integrations/vue/src/index.ts)、[`solid`](https://github.com/withastro/astro/blob/main/packages/integrations/solid/src/index.ts)
-**类型：** `(directive:` [`ClientDirectiveConfig`](https://github.com/withastro/astro/blob/00327c213f74627ac9ca1dec774efa5bf71e9375/packages/astro/src/%40types/astro.ts#L1872-L1875) `) => void;`
+**类型：** (directive: ClientDirectiveConfig) => void;
-**类型：** `(middleware:` [`AstroIntegrationMiddleware`](https://github.com/withastro/astro/blob/852ac0f75dfca1b2602e9cdbfa0447d9998e2449/packages/astro/src/%40types/astro.ts#L2124-L2127) `) => void;`
+**类型：** (middleware: AstroIntegrationMiddleware) => void;
-**类型：** [`RouteOptions`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/types/public/integrations.ts#L14-L27) +**类型：** `{ readonly component: string; prerender?: boolean; }`
具有 `component` 属性的对象用于标识路由，以及以下附加值，以允许你配置生成的路由：`prerender`。 @@ -612,7 +612,7 @@ function setPrerender() {-**类型：** [`IntegrationResolvedRoute[]`](#integrationroutedata-类型参考) +**类型：** [`IntegrationResolvedRoute[]`](#integrationresolvedroute)
一个包含了所有路由及其关联元数据的列表。 @@ -808,7 +808,7 @@ export default { 一个用于在 `astro dev` 时触发，以更新 content layer 的函数。可以这样使用，例如，要在开发时注册一个 webhook 端点，或者开启一个 socket 来监听 CMS 的改动。 -默认情况下，`refreshContent` 会刷新所有的集合。你可以选择性的提供一个 `loaders` 属性去传递，即一个包含着加载器（loader）名称的数组。如果提供的话，那么就只有使用了这些加载器的集合会被刷新。例如，一个 CMS 集成可以使用该属性来单独刷新它自己的集合。 +默认情况下，`refreshContent()` 会刷新所有的集合。你可以选择性的提供一个 `loaders` 属性去传递，即一个包含着加载器（loader）名称的数组。如果提供的话，那么就只有使用了这些加载器的集合会被刷新。例如，一个 CMS 集成可以使用该属性来单独刷新它自己的集合。 你也可以传递一个 `context` 对象给加载器。它可以用来传递任意数据，例如 webhook body，或者是来自 websocket 的事件。 @@ -871,10 +871,10 @@ export default {-**类型：** [`AddressInfo`](https://microsoft.github.io/PowerBI-JavaScript/interfaces/_node_modules__types_node_net_d_._net_.addressinfo.html) +**类型：** `AddressInfo`
-由 [Node.js Net 模块](https://nodejs.org/api/net.html) 提供的地址、协议族名和端口。 +由 [Node.js Net 模块的 `server.address()` 方法](https://nodejs.org/api/net.html#serveraddress) 提供的地址、协议族名和端口。 ### `astro:server:done` @@ -953,10 +953,10 @@ export default {
-**类型：** Map\
+**类型：** `Map
+
+**类型：** `string`
+
+ +**类型：** `string` +
+ +指定源组件的URL。 + +###### `route` + ++ +**类型：** [`RouteData`](#routedata) +
+ +描述关于页面路由的信息。 + +###### `moduleSpecifier` + ++ +**类型：** `string` +
+ +定义一个可以解析为模块文件路径的字符串。 + +###### `styles` + +
+
+**类型：** `Array<{ depth: number; order: number; sheet: { type: 'inline'; content: string } | { type: 'external'; src: string } }>`
+
@@ -1051,7 +1103,7 @@ export default {
-**类型：** [`SerializedSSRManifest`](https://github.com/withastro/astro/blob/3b10b97a4fecd1dfd959b160a07b5b8427fe40a7/packages/astro/src/core/app/types.ts#L91-L109) +**类型：** [`SerializedSSRManifest`](#已序列化的-ssr-清单属性)
允许你通过访问 SSR 清单来创建自定义构建。 @@ -1070,11 +1122,83 @@ export default { } ``` +##### 已序列化的 SSR 清单属性 + +[`SSRManifest`](#ssrmanifest) 的序列化版本，可通过 [`astro:build:ssr` 钩子](#astrobuildssr) 访问。它包含与 `SSRManifest` 相同的信息，但某些属性已转换为可序列化的格式。 + +###### `routes` + ++ +**类型：** `SerializedRouteInfo[]` +
+ +定义了一个序列化路由信息的列表。每个路由包含与 [`SSRManifest.routes`](#routes-1) 相同的属性，其中 `routeData` 被转换为 JSON 可序列化格式。 + +###### `assets` + ++ +**类型：** `string[]` +
+ +定义序列化资源文件路径的列表。 + +###### `componentMetadata` + +
+
+**类型：** [string, SSRComponentMetadata][]
+
+ +**类型：** `[string, string][]` +
+ +定义一组键值对数组，其中每一项都是一个元组。第一个元素是脚本标识符，第二个是脚本内容。 + +###### `clientDirectives` + +
+
+**类型：** `[string, string][]`
+
+
+**类型：** `[string, string][]`
+
+
+**类型：** `string`
+
-**类型：** Map\<IntegrationRouteData, URL\>
+**类型：** Map\<IntegrationRouteData, URL\>
-**类型：** [`IntegrationRouteData[]`](#integrationroutedata-类型参考) +**类型：** [`IntegrationRouteData[]`](#integrationroutedata)
所有生成的路由及其相关元数据的列表。 @@ -1232,7 +1360,7 @@ export default function myIntegration() {+ +**类型：** `{ order: "pre" | "post"; entrypoint: string | URL; }` +
+ +描述 [由集成添加的中间件](#addmiddleware-选项)。 + +#### `order` + ++ +**类型：** `"pre" | "post"` +
+ +指定中间件应该在其他中间件之前（`pre`）还是之后（`post`）运行。 + +#### `entrypoint` + ++ +**类型：** `string | URL` +
+ +定义中间件的导入路径。 + +### `AstroMiddlewareInstance` + +
+
+**类型：** \{ onRequest?: MiddlewareHandler; \}
+
+ +**类型：** `{ name: string; clientEntrypoint?: string | URL; serverEntrypoint: string | URL; }` +
+ +描述 [由集成添加的组件框架渲染器](#addrenderer-选项)。 + +#### `name` + ++ +**类型：** `string` +
+ +组件框架渲染器的名称。 + +#### `clientEntrypoint` + ++ +**类型：** `string | URL` +
+ +定义在使用你的组件时，在客户端运行的渲染器的导入路径。 + +#### `serverEntrypoint` + ++ +**类型：** `string | URL` +
+ +定义渲染器的导入路径，该渲染器在每次使用组件时的服务器端请求或静态构建期间运行。 + +### `ClientDirectiveConfig` + ++ +**类型：** `{ name: string; entrypoint: string | URL; }` +
+ +描述 [由集成添加的自定义客户端指令](#addclientdirective-选项)。 + +#### `name` + ++ +**类型：** `string` +
+ +指令触发事件的自定义名称。 + +#### `entrypoint` + ++ +**类型：** `string | URL` +
+ ### `HookParameters` -你可以通过将钩子的名称传递给 `HookParameters` 实用工具类型来获取钩子参数的类型。在以下示例中，输入了函数的 `options` 参数后，匹配到了 `astro:config:setup` 挂钩的参数： +你可以通过将钩子的名称传递给 `HookParameters` 实用工具类型来获取钩子参数的类型。 + +在以下示例中，输入了函数的 `options` 参数后，匹配到了 [`astro:config:setup` 钩子](#astroconfigsetup) 的参数： ```ts /HookParameters(?:<.+>)?/ import type { HookParameters } from 'astro'; @@ -1337,22 +1590,20 @@ function mySetup(options: HookParameters<'astro:config:setup'>) { } ``` -### `IntegrationResolvedRoute` 类型参考 +### `IntegrationResolvedRoute` + +具有重新映射属性的 [`RouteData`](#routedata) 子集。 ```ts -interface IntegrationResolvedRoute { +interface IntegrationResolvedRoute extends Pick< + RouteData, + 'generate' | 'params' | 'pathname' | 'segments' | 'type' | 'redirect' | 'origin' + > & { pattern: RouteData['route']; patternRegex: RouteData['pattern']; entrypoint: RouteData['component']; isPrerendered: RouteData['prerender']; redirectRoute?: IntegrationResolvedRoute; - generate: (data?: any) => string; - params: string[]; - pathname?: string; - segments: RoutePart[][]; - type: RouteType; - redirect?: RedirectConfig; - origin: 'internal' | 'external' | 'project'; } ``` @@ -1360,7 +1611,7 @@ interface IntegrationResolvedRoute {-**类型：** `string` +**类型：** [`RouteData['route']`](#route)
允许你根据路由的路径来识别路由的类型。以下是与其格式（pattern）相关联的路径的一些示例： @@ -1372,7 +1623,7 @@ interface IntegrationResolvedRoute {-**类型：** `RegExp` +**类型：** [`RouteData['pattern']`](#pattern-1)
允许你读取一个正则表达式，该表达式用于将输入的 URL 与请求的路由进行匹配。 @@ -1383,7 +1634,7 @@ interface IntegrationResolvedRoute {-**类型：** `string` +**类型：** [`RouteData['component']`](#component)
源组件的 URL 路径名。 @@ -1392,7 +1643,7 @@ interface IntegrationResolvedRoute {-**类型：** `boolean` +**类型：** [`RouteData['prerender']`](#prerender)
确定该路径是否使用 [按需渲染](/zh-cn/guides/on-demand-rendering/)。对于配置了以下内容的项目，该值将为 `true`： @@ -1408,6 +1659,41 @@ interface IntegrationResolvedRoute { 当 `IntegrationResolvedRoute.type` 的值为 `redirect` 时，该值将成为 `IntegrationResolvedRoute` 重定向的目标。否则，该值将为 undefined。 +### `RedirectConfig` + +
+
+**类型：** string | \{ status: ValidRedirectStatus; destination: string; \}
+
+ +**类型：** `string` +
+ +定义当前路由模式。以下是一些与其模式关联的路径示例： + +* `src/pages/index.astro` 会是 `/` +* `src/pages/blog/[...slug].astro` 会是 `/blog/[...slug]` +* `src/pages/site/[blog]/[...slug].astro` 会是 `/site/[blog]/[...slug]` + +#### `component` + ++ +**类型：** `string` +
+ +指定源组件的 URL。 + #### `generate()`@@ -1417,10 +1703,10 @@ interface IntegrationResolvedRoute { 该函数提供路由的可选参数，使用路由的格式对它们进行插值，然后返回路由的路径名。 -例如，对于诸如 `/blog/[...id].astro` 这样的路由，`generate` 函数将返回如下内容： +例如，对于诸如 `/blog/[...id].astro` 这样的路由，`generate()` 函数将返回如下内容： ```js -console.log(generate({ id: 'presentation' })) // 将打印 `/blog/presentation` +generate({ id: 'presentation' }) // 将输出 `/blog/presentation` ``` #### `params` @@ -1441,11 +1727,31 @@ console.log(generate({ id: 'presentation' })) // 将打印 `/blog/presentation` 对于常规的路由，该值即为路径名。而对于使用了 [动态路由](/zh-cn/guides/routing/#动态路由) 的项目（例如：`[dynamic]` 或 `[...spread]`），该路径名将为 undefined。 +#### `distURL` + +
+
+**类型：** `URL[] | undefined`
+
+ +**类型：** `RegExp` +
+ +指定用于将输入 URL 与请求的路由进行匹配的正则表达式。 + +例如，给定一个 `[fruit]/about.astro` 路径，正则表达式将是 `/^/([^/]+?)/about/?$/`。使用 `pattern.test("banana/about")` 将会返回 `true`。 + #### `segments`
-**类型：** RoutePart[][]
+**类型：** RoutePart[][]
-**类型：** `RouteType` +**类型：** [`RouteType`](#routetype) +
+ +允许你识别 [路由的类型](#routetype)。 + +#### `prerender` + ++ +**类型：** `boolean`
-允许你辨认路由的类型。该值可能为： -* `page`：基于文件系统的路由，通常为 Astro 组件 -* `endpoint`：基于文件系统的路径，通常为暴露了端点方法的 JS 文件 -* `redirect`：一个指向另一个基于文件系统的路径 -* `fallback`：一个不存在于文件系统中的路径并且需要其他方式来处理，通常是中间件 +确定路由是使用 [按需渲染](/zh-cn/guides/on-demand-rendering/) 还是在构建时静态预渲染。 + +另请参阅路由参考中的 [`prerendered`](/zh-cn/reference/routing-reference/#prerender)。 #### `redirect`
-**类型：** RedirectConfig | undefined
+*类型：** RedirectConfig | undefined
-**类型：** `'internal' | 'external' | 'project'` +**类型：** `RouteData | undefined`
-确定该路径是来自于 Astro 内核（`internal`），或来自于集成（`external`），还是来自于用户项目（`project`）。 +指定当 [`RouteData.type`](#type) 为 `redirect` 时要重定向到的 `RouteData`。 -##### `IntegrationRouteData` 类型参考 +#### `fallbackRoutes` -:::caution -该类型已于 v5.0 被弃用。请使用 [`IntegrationResolvedRoute`](#integrationresolvedroute-类型参考) 作为代替。 -::: +
-集成中使用的是 `RouteData` 的较小版本。
+**类型：** `RouteData[]`
+
-**类型：** `RouteType` +**类型：** `boolean`
-允许你辨认路由的类型。该值可能为： -- `page`：基于文件系统的路由，通常为 Astro 组件 -- `endpoint`：基于文件系统的路由，通常为暴露了端点方法的 JS 文件 -- `redirect`：一个指向另一个基于文件系统的路由 -- `fallback`：一个不存在于文件系统的路由并且需要其他方式来处理，通常是中间件 +指定路由是否为目录索引（例如 `src/pages/index.astro`、`src/pages/blog/index.astro`）。 -#### `component` +#### `origin`
-**类型：** `string`
+**类型：** `'internal' | 'external' | 'project'`
+
-**类型：** `string | undefined` +**类型：** `{ content: string; dynamic: boolean; spread: boolean; }`
-对于常规的路由，该值即为路径名。而对于使用了 [动态路由](/zh-cn/guides/routing/#动态路由) 的项目（例如：`[dynamic]` 或 `[...spread]`），该路径名将为 undefined。 +描述一个路由段。 -#### `pattern` +#### `content`-**类型：** `RegExp` +**类型：** `string`
-允许你读取一个正则表达式，该表达式用于将输入的 URL 与请求的路由进行匹配。 +指定路由的参数名称。例如： -例如，给定一个 `[fruit]/about.astro` 路径，将生成这样的格式：`/^\/([^/]+?)\/about\/?$/`。那么使用 `pattern.test("banana/about")` 就会返回 `true`。 +* `about.astro` 的名称是 `about` +* `[slug].astro` 的名称是 `slug` +* `[...id].astro` 的名称是 `id` -#### `params` +#### `dynamic`-**类型：** `string[]` +**类型：** `boolean`
-允许你读取路由的 `params`。例如，当一个项目使用以下的 [动态路由](/zh-cn/guides/routing/#动态路由) `/pages/[lang]/[...slug].astro`时，该值将会是 `['lang', '...slug']`。 +路由是否是动态的。 -#### `segments` +#### `spread`-**类型：** `{ content: string; dynamic: boolean; spread: boolean; }[][]` +**类型：** `boolean`
-允许你读取路由的 [`params`](#params-1)，它有着额外的元数据。每个对象都包含了以下属性： -* `content`：`param` 的名称， -* `dynamic`：路由是否为动态， -* `spread`：动态路由是否使用了展开语法。 - -例如，以下的路由 `/pages/[lang]/index.astro` 将会输出这样的分段（segments）`[[ { content: 'lang', dynamic: true, spread: false } ]]`。 +动态路由是否使用展开语法。 -#### `generate()` +### `RouteType`-**类型：** `(data?: any) => string` +**类型：** `'page' | 'endpoint' | 'redirect' | 'fallback'`
-该函数提供路由的可选参数，使用路由的格式对它们进行插值，然后返回路由的路径名。 +支持的路由类型的联合类型 -例如，对于诸如 `/blog/[...id].astro` 这样的路由，`generate` 函数将返回如下内容： +* `page`: 位于文件系统中的路由，通常是一个 Astro 组件 +* `endpoint`: 存在于文件系统中的路由，通常是一个暴露端点方法的 JS 文件 +* `redirect`: 一个路由指向文件系统中存在的另一个路由 +* `fallback`: 一个在文件系统中不存在的路由，需要通过其他方式处理，通常使用中间件 -```js -console.log(generate({ id: 'presentation' })) // 将打印 `/blog/presentation` -``` +### `SSRComponentMetadata` -#### `prerender` ++ +**类型：** `{ propagation: PropagationHint; containsHead: boolean; }` +
+ +描述服务器渲染的组件的构建元数据。 + +#### `propagation`-**类型：** `boolean` +**类型：** `'none' | 'self' | 'in-tree'`
-确定路由是否被预渲染。 +关于如何从该组件渲染 head 内容的描述，包括 Astro 运行时是否需要等待组件： +- `none`：该组件不传递 head 内容。 +- `self`：该组件追加 head 内容。 +- `in-tree`：该组件的依赖树中的另一个组件追加 head 内容。 -#### `distURL` +#### `containsHead`-**类型：** `URL[] | undefined` +**类型：**: `boolean`
-该路由所发出的文件的物理路径。当路径 **没有** 被预渲染时，该值可能为 `undefined` 或空数组。 +确定组件是否包含头部内容。 -#### `redirect` +### `SSRLoadedRenderer`
-**类型：** RedirectConfig | undefined
+**类型：** `{ name: string; clientEntrypoint?: string | URL; ssr: SSRLoadedRendererValue; }`
+ +**类型：** [`SSRLoadedRendererValue`](#ssrloadedrenderervalue) +
+ +定义此框架的服务器使用的函数和配置。 + +### `SSRLoadedRendererValue` + +包含从特定 UI 框架在服务器上渲染组件所需的函数和配置。 + +#### `name` + ++ +**类型：** `string` +
+ +指定渲染器的名称标识符。 + +#### `check()` + +
+
+**类型：** `AsyncRendererComponentFn
+
+**类型：** `AsyncRendererComponentFn<{ html: string; attrs?: Record
+
+**类型：** `boolean`
+
+
+**类型：** `() => string`
+
+
+**类型：** `string`
+
+ +**类型：** `string` +
+ +定义用于按需渲染的 [服务器适配器](/zh-cn/guides/on-demand-rendering/#服务器适配器) 名称。 + +#### `routes` + ++ +**类型：** `RouteInfo[]` +
+ +此项目中可用路由的信息列表。每个条目包含以下属性。 + +##### `routeData` + ++ +**类型：** [`RouteData`](#routedata) +
+ +一个描述路由已知信息的对象。 + +##### `file` + ++ +**类型：** `string` +
+ +指定构建路由入口点的文件路径。 + +##### `links` + ++ +**类型：** `string[]` +
+ +定义此路由所需的 [HTML `link` 元素](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/link) 列表。 + +##### `scripts` + ++ +**类型：** `Array<{ children: string; stage: string } | { type: 'inline' | 'external'; value: string }>` +
+ +定义与此路由关联的脚本列表。这包括具有 `children` 和 `stage` 属性的集成注入脚本，以及具有 `type` 和 `value` 属性的提升脚本。 + +##### `styles` + +
+
+**类型：** `Array<{ type: "inline"; content: string; } | { type: "external"; src: string; }>`
+
+ +**类型：** `string` +
+ +指定 [已配置的 `site`](/zh-cn/reference/configuration-reference/#site)。 + +#### `base` + ++ +**类型：** `string` +
+ +指定 [已配置的 `base` 路径](/zh-cn/reference/configuration-reference/#base)。 + +#### `userAssetsBase` + +
+
+**类型：** `string | undefined`
+
+
+**类型：** [`AstroConfig['trailingSlash']`](/zh-cn/reference/configuration-reference/#trailingslash)
+
+
+**类型：** [`NonNullable
+
+
+**类型：** `boolean`
+
+
+**类型：** `string | ({ fallback: string; } & Record
+
+
+**类型：** SSRLoadedRenderer[]
+
+
+**类型：** `Map
+
+
+**类型：** `Record
+
+**类型：** `Map
+
+
+**类型：** `Set
+
+**类型：** Map\
+
+
+**类型：** `{ page: ImportComponentInstance; onRequest?: MiddlewareHandler; renderers: SSRLoadedRenderer[]; }`
+
+
+**类型：** `() => Promise
+
+**类型：** [`MiddlewareHandler`](/zh-cn/reference/modules/astro-middleware/#middlewarehandler)
+
+
+**类型：** SSRLoadedRenderer[]
+
+
+**类型：** Map\
+
+
+**类型：** `Map
+
+
+**类型：** `Map
+
+
+**类型：** `Promise
+
+
+**类型：** `SSRManifestI18n | undefined`
+
+ +**类型：** `"manual" | "pathname-prefix-always" | "pathname-prefix-other-locales" | "pathname-prefix-always-no-redirect" | "domains-prefix-always" | "domains-prefix-other-locales" | "domains-prefix-always-no-redirect"` +
+ +定义已配置的 [i18n 路由策略](/zh-cn/reference/configuration-reference/#i18nrouting)。这决定了如何在 URL 中处理语言区域设置以及是否发生重定向。 + +##### `locales` + ++ +**类型：** `Locales` +
+ +确定 [项目中配置的受支持语言环境](/zh-cn/reference/configuration-reference/#i18nlocales) 设置列表。 + +##### `defaultLocale` + ++ +**类型：** `string` +
+ +确定 [项目中配置的默认语言环境](/zh-cn/reference/configuration-reference/#i18ndefaultlocale)。 + +##### `fallback` + +
+
+**类型：** `Record
+ +**类型：** `"redirect" | "rewrite"` +
+ +确定 [项目的配置回退策略](/zh-cn/reference/configuration-reference/#i18nroutingfallbacktype)。 + +##### `domainLookupTable` + +
+
+**类型：** `Record
+
+**类型：** () => Promise\<AstroMiddlewareInstance\> | AstroMiddlewareInstance
+
+
+**类型：** () => Promise\<\{ server: Record\
+
+
+**类型：** `boolean`
+
+
+**类型：** Partial\<RemotePattern\>[]
+
+
+**类型：** SessionConfig\
+
+
+**类型：** `string | URL`
+
+
+**类型：** `string | URL`
+
+
+**类型：** `string | URL`
+
+
+**类型：** `string | URL`
+
+
+**类型：** `string | URL`
+
+
+**类型：** `string | URL`
+
+
+**类型：** SSRManifestCSP | undefined
+
+
+**类型：** `Record
+
+
+
+ +**类型：** `'adapter' | 'meta' | 'header' | undefined` +
+ +指定 CSP 指令应作为 `meta` 元素注入、作为响应 `header` 注入，还是在 [`adapter` 支持设置响应头时](/zh-cn/reference/adapter-reference/#experimentalstaticheaders) 由适配器注入。 + +#### `algorithm` + ++ +**类型：** `'SHA-256' | 'SHA-384' | 'SHA-512'` +
+ +指定 [配置的哈希函数](/zh-cn/reference/experimental-flags/csp/#algorithm)。 + +#### `scriptHashes` + ++ +**类型：** `string[]` +
+ +指定项目脚本的生成哈希列表和外部脚本的 [用户提供哈希](/zh-cn/reference/experimental-flags/csp/#hashes)。 + +#### `scriptResources` + ++ +**类型：** `string[]` +
+ +指定一个有效源列表，该列表结合了 [已配置的脚本资源](/zh-cn/reference/experimental-flags/csp/#resources) 和 [注入的脚本资源](/zh-cn/reference/experimental-flags/csp/#cspinsertstyleresource)。 + +#### `isStrictDynamic` + ++ +**类型：** `boolean` +
+ +确定 [配置中是否启用了对动态脚本注入的支持](/zh-cn/reference/experimental-flags/csp/#strictdynamic)。 + +#### `styleHashes` + ++ +**类型：** `string[]` +
+ +指定项目样式的生成哈希列表和外部样式的 [用户提供哈希列表](/zh-cn/reference/experimental-flags/csp/#hashes)。 + +#### `styleResources` + ++ +**类型：** `string[]` +
+ +指定一个有效来源列表,该列表结合 [了已配置的样式资源](/zh-cn/reference/experimental-flags/csp/#resources) 和 [注入的样式资源](/zh-cn/reference/experimental-flags/csp/#cspinsertstyleresource)。 + +#### `directives` + ++ +**类型：** `CspDirective[]` +
+ +指定特定内容类型的 [有效来源的配置列表](/zh-cn/reference/experimental-flags/csp/#directives)。 + +### `ValidRedirectStatus` + ++ +**类型：** `301 | 302 | 303 | 307 | 308 | 300 | 304` +
+ +支持的重定向状态码的联合类型。 + +### 已弃用的类型导入 + +以下类型已被弃用，将在未来的主要版本中移除： + +#### `IntegrationRouteData` + +:::caution +此类型自 v5.0 版本起已弃用。请改用 [`IntegrationResolvedRoute`](#integrationresolvedroute)。 +::: + +在集成中使用的 [`RouteData`](#routedata) 的精简版本。 + +```ts +type IntegrationRouteData = Omit< + RouteData, + 'isIndex' | 'fallbackRoutes' | 'redirectRoute' | 'origin' +> & { + redirectRoute?: IntegrationRouteData; +}; +``` + +##### `redirectRoute`**类型：** `IntegrationRouteData | undefined`
-当 `RouteData.type` 的值为 `redirect` 时，该值将包含要重定向到的路由的 `IntegrationRouteData`。否则，该值将为 undefined。 +当 [`RouteData.type`](#type) 的值为 `redirect` 时，该值将包含要重定向到的路由的 `IntegrationRouteData`。否则，该值将为 undefined。 ## 使用 `astro add` 安装