跳转到内容

Astro 集成 API

Astro 集成只需几行代码就能为你的项目添加新的功能和行为。

这个参考页是为任何想要编写集成的人准备的。要学习如何在项目中使用集成,请查看我们的使用集成指南。

当你创建自己的集成时,可以参考官方的 Astro 集成。

interface AstroIntegration {
name: string;
hooks: {
'astro:config:setup'?: (options: {
config: AstroConfig;
command: 'dev' | 'build' | 'preview' | 'sync';
isRestart: boolean;
updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
addRenderer: (renderer: AstroRenderer) => void;
addWatchFile: (path: URL | string) => void;
addClientDirective: (directive: ClientDirectiveConfig) => void;
addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
addDevToolbarApp: (pluginEntrypoint: string) => void;
injectScript: (stage: InjectedScriptStage, content: string) => void;
injectRoute: (injectedRoute: { pattern: string, entrypoint: string }) => void;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;
'astro:config:done'?: (options: {
config: AstroConfig;
setAdapter: (adapter: AstroAdapter) => void;
injectTypes: (injectedType: { filename: string; content: string }) => URL;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;
'astro:route:setup'?: (options: { route: RouteOptions; logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:server:setup'?: (options: { server: vite.ViteDevServer; logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:server:start'?: (options: { address: AddressInfo; logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:server:done'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:build:start'?: (options: { logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:build:setup'?: (options: {
vite: ViteConfigWithSSR;
pages: Map<string, PageBuildData>;
target: 'client' | 'server';
logger: AstroIntegrationLogger;
}) => void | Promise<void>;
'astro:build:generated'?: (options: { dir: URL; logger: AstroIntegrationLogger; }) => void | Promise<void>;
'astro:build:ssr'?: (options: {
manifest: SerializedSSRManifest;
entryPoints: Map<RouteData, URL>;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;
'astro:build:done'?: (options: { dir: URL; routes: RouteData[]; logger: AstroIntegrationLogger; }) => void | Promise<void>;
// ...任何来自集成的自定义钩子
};
}

Astro 提供了集成可以实现的钩子,以便在 Astro 生命周期的某些部分执行。Astro 钩子被定义在 IntegrationHooks 接口中,该接口是全局 Astro 命名空间的一部分。

Astro 内置了以下钩子:

下一个钩子astro:config:done

时机:初始化时,在 ViteAstro 配置 解析前。

用途:扩展项目配置。包括更新 Astro 配置、应用 Vite 插件、添加组件渲染器,以及向页面注入脚本。

'astro:config:setup'?: (options: {
config: AstroConfig;
command: 'dev' | 'build' | 'preview' | 'sync';
isRestart: boolean;
updateConfig: (newConfig: DeepPartial<AstroConfig>) => AstroConfig;
addRenderer: (renderer: AstroRenderer) => void;
addClientDirective: (directive: ClientDirectiveConfig) => void;
addMiddleware: (middleware: AstroIntegrationMiddleware) => void;
addDevToolbarApp: (pluginEntrypoint: string) => void;
addWatchFile: (path: URL | string) => void;
injectScript: (stage: InjectedScriptStage, content: string) => void;
injectRoute: ({ pattern: string, entrypoint: string }) => void;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;

类型AstroConfig

用户提供的 Astro 配置只读副本。这是在任何其他集成运行之前进行解析的。如果在所有集成完成配置更新后需要配置副本,astro:config:done 钩子

类型: 'dev' | 'build' | 'preview' | 'sync'

  • dev - 项目执行 astro dev
  • build - 项目执行 astro build
  • preview - 项目执行 astro preview
  • sync - 项目执行 astro sync

类型boolean

开发服务器启动时为false,触发重载时为true。用于检测此函数何时被多次调用。

类型(newConfig: DeepPartial<AstroConfig>) => AstroConfig;

用来更新用户提供的Astro 配置的回调函数。你提供的任何配置将与用户配置 + 其他集成配置的更新合并,所以你可以随意省略键名!

例如,假设你需要在项目使用 Vite 插件:

import bananaCSS from '@vitejs/official-banana-css-plugin';
export default {
name: 'banana-css-integration',
hooks: {
'astro:config:setup': ({ updateConfig }) => {
updateConfig({
vite: {
plugins: [bananaCSS()],
}
})
}
}
}

类型(renderer: AstroRenderer ) => void;
示例litsveltereactpreactvuesolid

用于添加组件框架渲染器(即 React、Vue、Svelte 等)的回调函数。你可以浏览上面的例子和类型定义,了解更多的高级选项,但需要注意两个注意选项:

  • clientEntrypoint - 当组件被使用时,在客户端执行的文件的路径。这主要是为了使用 JS 渲染或填充你的组件。
  • serverEntrypoint - 文件路径,在服务器端请求或静态构建时,只要使用组件就会执行。这些文件应该将组件渲染成静态标记,并在适当的时候使用钩子进行激活。React 的 renderToString 回调函数是个典型例子。

类型URL | string

如果你的集成依赖于一些 Vite 不监听或者需要完整的开发服务器重启才能生效的配置文件,请用addWatchFile 添加它。每当该文件发生变化,Astro 开发服务器将重新加载(你可以用isRestart检查何时发生重新加载)。

使用示例:

// 必须是绝对路径!
addWatchFile('/home/user/.../my-config.json');
addWatchFile(new URL('./tailwind.config.js', config.root));

添加于: astro@2.6.0

类型: (directive: ClientDirectiveConfig ) => void;

添加一个 自定义客户端指令,用于在 .astro 文件中使用。

请注意,指令入口点仅通过 esbuild 进行打包,并且应保持较小,以避免减慢组件注水的速度。

示例用法:

astro.config.mjs
import { defineConfig } from 'astro/config';
import clickDirective from './astro-click-directive/register.js'
// https://astro.build/config
export default defineConfig({
integrations: [
clickDirective()
],
});
astro-click-directive/register.js
/**
* @type {() => import('astro').AstroIntegration}
*/
export default () => ({
name: "client:click",
hooks: {
"astro:config:setup": ({ addClientDirective }) => {
addClientDirective({
name: "click",
entrypoint: "./astro-click-directive/click.js",
});
},
},
});
astro-click-directive/click.js
/**
* 第一次触发 window 上的点击事件时进行激活
* @type {import('astro').ClientDirective}
*/
export default (load, opts, el) => {
window.addEventListener('click', async () => {
const hydrate = await load()
await hydrate()
}, { once: true })
}

你还可以在库的类型定义文件中为指令添加类型:

astro-click-directive/index.d.ts
import 'astro'
declare module 'astro' {
interface AstroClientDirectives {
'client:click'?: boolean
}
}

添加于: astro@3.4.0

类型: (pluginEntrypoint: string) => void;

添加一个自定义的开发工具栏应用

使用示例:

astro.config.mjs
import { defineConfig } from 'astro/config';
import devToolbarIntegration from './astro-dev-toolbar-app/integration.js'
// https://astro.build/config
export default defineConfig({
integrations: [
devToolbarIntegration()
],
});
astro-dev-toolbar-app/integration.js
/**
* @type {() => import('astro').AstroIntegration}
*/
export default () => ({
name: "dev-toolbar-app",
hooks: {
"astro:config:setup": ({ addDevToolbarApp }) => {
addDevToolbarApp("./astro-dev-toolbar-app/plugin.js");
},
},
});
astro-dev-toolbar-app/app.js
/**
* @type {import('astro').DevToolbarApp}
*/
export default {
id: "my-app",
name: "My App",
icon: "<svg>...</svg>",
init() {
console.log("I'm a dev toolbar app!")
},
};

添加于: astro@3.5.0

类型: (middleware: AstroIntegrationMiddleware ) => void;

添加中间件以在每个请求上运行。接受包含中间件的 entrypoint 模块,以及一个 order 参数来指定它应该在其他中间件之前(pre)运行还是之后(post)运行。

@my-package/integration.js
/**
* @type {() => import('astro').AstroIntegration}
*/
export default () => ({
name: "my-middleware-package",
hooks: {
"astro:config:setup": ({ addMiddleware }) => {
addMiddleware({
entrypoint: '@my-package/middleware',
order: 'pre'
});
},
},
});

中间件在一个包中定义,它有一个对应的 onRequest 函数,就像用户定义的中间件一样。

@my-package/middleware.js
import { defineMiddleware } from 'astro:middleware';
export const onRequest = defineMiddleware(async (context, next) => {
if(context.url.pathname === '/some-test-path') {
return Response.json({
ok: true
});
}
return next();
});

类型({ pattern: string, entrypoint: string }) => void;

用于向 Astro 项目注入路由的回调函数。注入的路由可以是 .astro页面.js.ts路由处理程序

injectRoute 接收带有 patternentrypoint 的对象值。

  • pattern - 应该在浏览器中使用的路由,例如 /foo/barpattern 可以使用 Astro 的文件路径语法来表示动态路由,例如 /foo/[bar]/foo/[...bar]。请注意,在 pattern无需文件扩展名。
  • entrypoint — 裸模块指定器,指向 .astro 页面或 .js/.ts 路由处理程序,处理pattern 中指定路由。
injectRoute({
// 使用 Astro 语法模式来匹配动态路由
pattern: '/subfolder/[dynamic]',
// 使用相对路径语法来匹配本地路由
entrypoint: './src/dynamic-page.astro'
});

对于设计用于安装在其他项目中的集成,使用其包名来引用路由的入口点。

下面的示例展示了一个以 @fancy/dashboard 发布到 npm 上的包,在路由中注入一个仪表盘:

injectRoute({
pattern: '/fancy-dashboard',
entrypoint: '@fancy/dashboard/dashboard.astro'
});

当你将你的包(在这个例子中是 @fancy/dashboard)发布到 npm 上时,你必须在你的 package.json 中导出 dashboard.astro

package.json
{
"name": "@fancy/dashboard",
// ...
"exports": { "./dashboard.astro": "./dashboard.astro" }
}

类型(stage: InjectedScriptStage, content: string) => void;

回调函数,在每个页面上注入 JavaScript 内容。

stage 表示这个脚本(content)应该如何插入。有些阶段允许不加修改地插入脚本,而有些阶段允许在 Vite 的捆绑步骤中进行压缩:

  • head-inline:注入每个页面的 <head> 中的脚本标签。由 Vite 压缩或解析。

  • before-hydration:在激活脚本运行之前导入客户端。由 Vite 优化和解决。

  • page:与 head-inline 类似,只是注入片段由 Vite 进行处理,并与页面上 Astro 组件内定义的其他 <script> 标签捆绑在一起。该脚本将在最终的页面输出中以 <script type="module"> 的形式加载,并由 Vite 压缩和解析。

  • page-ssr:在每个 Astro 页面组件的 frontmatter 中作为单独的模块被导入。因为这个阶段导入你的脚本,无法使用全局 Astro,脚本只会在 import 第一次 evaluate 时运行一次。

    page-ssr 阶段的主要是将 CSS import 注入到每个页面,并由 Vite 进行优化和解析。

    injectScript('page-ssr', 'import "global-styles.css";');

上一个钩子astro:config:setup

下一个钩子:当在开发模式下运行时为 astro:server:setup,在生产构建时为 astro:build:start

时机:在 Astro 配置解析后,其他集成已经运行 astro:config:setup 钩子后。

原因:检索最终的配置,以便在其他钩子中使用。

'astro:config:done'?: (options: {
config: AstroConfig;
setAdapter: (adapter: AstroAdapter) => void;
injectTypes: (injectedType: { filename: string; content: string }) => URL;
logger: AstroIntegrationLogger;
}) => void | Promise<void>;

类型:AstroConfig

用户提供的 Astro 配置的只读副本。这在其他集成运行后进行解析。

类型:(adapter: AstroAdapter) => void;

使集成成为适配器。在适配器 API中阅读更多内容。

添加于: astro@4.14.0

类型:(injectedType: { filename: string; content: string }) => URL

允许你通过添加一个新的 *.d.ts 文件将类型注入到用户的项目中。

filename 属性将用于在 /.astro/integrations/<normalized_integration_name>/<normalized_filename>.d.ts 生成文件,必须以 ".d.ts" 结尾。

content 属性将用于在文件中生成内容,必须是有效的 TypeScript。

此外,injectTypes() 返回一个 URL,指向规范化路径,以便稍后覆盖其内容,或以任何你想要的方式操作它。

const path = injectTypes({
filename: "types.d.ts",
content: "declare module 'virtual:integration' {}"
})
console.log(path) // URL

上一个钩子astro:config:done

下一个钩子astro:server:start

时机:在开发模式下创建 Vite 服务器后,但在 listen() 事件触发前。详见Vite 的 createServer API

用途:更新 Vite 服务端选项和中间件。

'astro:server:setup'?: (options: { server: vite.ViteDevServer }) => void | Promise<void>;

类型ViteDevServer

在开发模式下使用的 Vite 服务器的可变实例。例如,在 Partytown 集成中使用,以注入 Partytown 服务器作为中间件。

export default {
name: 'partytown',
hooks: {
'astro:server:setup': ({ server }) => {
server.middlewares.use(
function middleware(req, res, next) {
// 处理请求
}
);
}
}
}

上一个钩子astro:server:setup

下一个钩子astro:server:done

时机:在服务端 listen() 事件触发之后。

用途:拦截指定地址的网络请求。如果你打算将这个地址用于中间件,请考虑使用 astro:server:setup 来代替。

'astro:server:start'?: (options: { address: AddressInfo }) => void | Promise<void>;

类型AddressInfo

Node.js Net 模块提供的地址、协议族名和端口。

上一个钩子astro:server:start

时机:在开发服务器关闭后。

用途:在运行 astro:server:setupastro:server:start 钩子中可能触发的清理事件。

'astro:server:done'?: () => void | Promise<void>;

上一个钩子astro:config:done

下一个钩子astro:build:setup

时机:在 astro:config:done 事件之后,但在生产构建开始前。

用途:设置生产构建过程中需要的任何全局对象或客户端。这也可以扩展适配器 API中的构建配置选项。

'astro:build:start'?: () => void | Promise<void>;

上一个钩子astro:build:start

下一个钩子astro:build:ssr

时机:在 astro:build:start 钩子后,在构建之前立即运行。

用途:此时,用于构建的 Vite 配置已经完全建成,这是你修改它的最后机会。例如,这可以用来覆盖一些默认值。如果你不确定你应该使用这个钩子还是 astro:build:start,请使用 astro:build:start

'astro:build:setup'?: (options: {
vite: ViteConfigWithSSR;
pages: Map<string, PageBuildData>;
target: 'client' | 'server';
}) => void | Promise<void>;

上一个钩子astro:build:setup

时机:在静态生产构建完成生成路由和资源之后。

用途:在清理构建产物之前访问生成的路由和资源。这是一个非常不常见的用例。我们建议使用astro:build:done,除非你真的需要在清理前访问生成的文件。

'astro:build:generated'?: (options: { dir: URL }) => void | Promise<void>;

上一个钩子astro:build:setup

时机:在生产 SSR 构建完成之后。

原因:获取 SSR manifest,这在插件或集成中创建自定义 SSR 构建时很有用。

  • entryPoints 将页面路由映射到构建后的物理文件;
  • middlewareEntryPoint 是中间件文件的文件系统路径。
'astro:build:ssr'?: (options: {
manifest: SerializedSSRManifest,
entryPoints: Map<RouteData, URL>,
middlewareEntryPoint: URL
}) => void | Promise<void>;

上一个钩子astro:build:ssr

时机:在生产构建(SSG 或 SSR)完成后。

用途:访问生成的路由和资产进行扩展(例如,将内容复制到生成的 /assets 目录)。如果你打算转换生成的资源,我们建议探索 Vite 插件 API通过 astro:config:setup 进行配置来代替。

'astro:build:done'?: (options: { dir: URL; routes: RouteData[], pages: { pathname: string }[] }) => void | Promise<void>;

类型URL

指向构建输出目录的链接。注意,如果你需要有效的绝对路径字符串,你应该使用 Node 内置的 fileURLToPath 工具。

import { writeFile } from 'node:fs/promises';
import { fileURLToPath } from 'node:url';
export default function myIntegration() {
return {
hooks: {
'astro:build:done': async ({ dir }) => {
const metadata = await getIntegrationMetadata();
// 使用 fileURLToPath 获得有效、跨平台绝对路径字符串
const outFile = fileURLToPath(new URL('./my-integration.json', dir));
await writeFile(outFile, JSON.stringify(metadata));
}
}
}
}

类型:RouteData[]

所有生成的路由及其相关元数据的列表。

你可以参考下面完整的 RouteData 类型,但最常见的属性是。

  • component - 相对于项目根的输入文件路径
  • pathname - 输出文件的 URL(对于使用 [dynamic][...spread] 参数的路由未定义)。
interface RouteData {
/** 指定路由是 HTML 页面还是非 HTML 端点 */
type: 'page' | 'endpoint';
/** 组件源码链接 */
component: string;
/**
* 将使用的输出链接路径名
* 注意:[dynamic] 和 [...spread] 路由将为 undefined
*/
pathname?: string;
/**
* 用于匹配输入链接和请求的路由的正则表达式
* 如 `[fruit]/about.astro` 将生成 /^\/([^/]+?)\/about\/?$/ 匹配模式
* pattern.test("banana/about") 为 `true`
*/
pattern: RegExp;
/**
* 动态和扩展路由参数
* 如 `/pages/[lang]/[..slug].astro` 将输出参数 ['lang', '...slug']
*/
params: string[];
/**
* 类似于 `params` 字段,但有更多相关的元数据
* 如 `/pages/[lang]/index.astro` 将输出分段
* [[ { content: 'lang', dynamic: true, spread: false } ]]
*/
segments: { content: string; dynamic: boolean; spread: boolean; }[][];
/**
* 根据输入数据中就地渲染组件的函数。
* 这通常仅在内部使用,所以请谨慎调用!
*/
generate: (data?: any) => string;
}

类型: { pathname: string }[]

生成的所有页面的列表是一个包含一个属性的对象。

  • pathname - 页面的最终路径。

添加于: astro@4.14.0

时机:astro dev 中,每当请求一个路由时。在 astro build 中,当打包和转换路由文件时。

原因: 在构建或请求时为路由设置选项,例如启用按需服务器渲染

'astro:route:setup'?: (options: { route: RouteOptions }) => void | Promise<void>;

类型:RouteOptions

具有 component 属性的对象用于标识路由,以及以下附加值,以允许你配置生成的路由:prerender

component 属性是一个相对于项目根目录的只读字符串路径,例如 "src/pages/blog/[slug].astro"

类型:boolean
默认值:undefined

添加于: astro@4.14.0

prerender 属性用于配置按需服务器渲染的路由。如果路由文件包含一个显式的 export const prerender 值,该值将被用作默认值,而不是 undefined

astro.config.mjs
import { defineConfig } from 'astro/config';
export default defineConfig({
integrations: [setPrerender()],
});
function setPrerender() {
return {
name: 'set-prerender',
hooks: {
'astro:route:setup': ({ route }) => {
if (route.component.endsWith('/blog/[slug].astro')) {
route.prerender = true;
}
},
},
};
}

如果在运行所有钩子后的最终值是 undefined,路由将根据 output 选项 回退到预渲染的默认值:hybrid 模式下预渲染,server 模式下按需渲染。

通过 全局增强 来扩展 IntegrationHooks 接口,可以将自定义钩子添加到集成中。

declare global {
namespace Astro {
export interface IntegrationHook {
'your:hook': (params: YourHookParameters) => Promise<void>
}
}
}

Astro 为未来的内置钩子保留了 astro: 前缀。请在命名时,为自定义钩子选择不同的前缀。

你可以通过将钩子的名称传递给 HookParameters 实用工具类型来获取钩子参数的类型。在以下示例中,输入了函数的 options 参数后,匹配到了 astro:config:setup 挂钩的参数:

import type { HookParameters } from 'astro';
function mySetup(options: HookParameters<'astro:config:setup'>) {
options.updateConfig({ /* ... */ });
}

用户可以使用 astro add 命令 轻松地在他们的项目中添加集成和适配器。如果你想让别人可以使用这个工具安装你的集成,在你的 package.json 中的 keywords 字段中添加 astro-integration

{
"name": "example",
"keywords": ["astro-integration"],
}

在你将集成发布到 npm后,即可运行 astro add example 安装包和 package.json 中指定的对等依赖。同时也会将你的集成应用到用户的 astro.config 中,就像这样:

astro.config.mjs
import { defineConfig } from 'astro/config';
import example from 'example';
export default defineConfig({
integrations: [example()],
})

Astro 日志记录器的实例,用于写日志。此日志记录器使用与 CLI 配置的相同的日志级别

用于写入终端的可用方法

  • logger.info("Message");
  • logger.warn("Message");
  • logger.error("Message");
  • logger.debug("Message");

所有消息都前面带有一个具有集成名字的标签。

integration.ts
import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
return {
name: "astro-format",
hooks: {
"astro:build:done": ({ logger }) => {
// do something
logger.info("Integration ready.");
}
}
}
}

上面的示例将记录一个包含提供的 info 消息的日志:

Terminal window
[astro-format] Integration ready.

要使用不同的标签记录一些日志,请使用 .fork 方法指定一个新的 name

integration.ts
import type { AstroIntegration } from "astro";
export function formatIntegration(): AstroIntegration {
return {
name: "astro-format",
hooks: {
"astro:config:done": ({ logger }) => {
// do something
logger.info("Integration ready.");
},
"astro:build:done": ({ logger }) => {
const buildLogger = logger.fork("astro-format/build");
// do something
buildLogger.info("Build finished.")
}
}
}
}

上面的示例将默认生成带有 [astro-format] 的日志,并在指定名字时生成带有 [astro-format/build] 的日志:

Terminal window
[astro-format] Integration ready.
[astro-format/build] Build finished.

所有的集成都是按照配置的顺序运行的。例如,在 astro.config.* 中的数组 [react(), svelte()]react 将在 svelte 之前运行。

你的集成最好能以任何顺序运行。如果不行我们建议在文档中注明你的集成需要排在 integrations 配置数组的第一位或最后一位。

一个集成也可以写成多个较小集成的集合。我们称这些集合为预设。预设不是创建返回单个集成对象的工厂函数,而是返回集成对象的数组。这对于从多个集成中构建复杂的功能非常有用。

integrations: [
// 示例:examplePreset() 将返回 [integrationOne, integrationTwo, ...etc]
examplePreset()
]
贡献

你有什么想法?

社区