跳转到内容

使用集成

使用 Astro 集成只需几行代码就能为你的项目添加新的功能和行为。你可以使用官方集成，社区构建的集成，甚至可以 构建自己的自定义集成。

集成能够…

  • 使用 渲染器 解锁 React、Vue、Svelte、Solid 和其他流行的 UI 框架。
  • 使用 SSR 适配器 启用按需渲染。
  • 只需几行代码就能整合 Tailwind 和 Partytown 等工具。
  • 为你的项目添加新功能，如自动生成网站地图。
  • 编写自定义代码，与构建过程、开发服务器等挂钩。

官方集成

段落标题 官方集成

以下集成由 Astro 维护。

UI 框架

SSR 适配器

其他集成

自动集成设置

段落标题 自动集成设置

Astro 包含了一个 astro add 命令来自动设置官方集成。许多社区插件也可以使用这个命令添加。请查阅每个集成的文档，以确定是否支持 astro add，或者你是否需要手动安装。

只需用你的包管理器运行 astro add 命令，我们的自动集成向导将更新你的配置文件并安装任何必要的依赖。

Terminal window
npx astro add react

甚至还可以同时配置多个集成！

Terminal window
npx astro add react tailwind partytown

手动安装

段落标题 手动安装

Astro 集成总是添加在 astro.config.mjs 文件中的 integrations 属性。

有三种常见的方法来导入集成到你的 Astro 项目：

  1. 安装 npm 包集成。

  2. 从项目内部的本地文件导入你自己的集成。

  3. 直接在配置文件中内联编写集成。

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import installedIntegration from '@astrojs/vue';
    import localIntegration from './my-integration.js';
    

    export default defineConfig({
      integrations: [
        // 1. 从已安装的 npm 包中导入
        installedIntegration(),
        // 2. 从本地 JS 文件导入
        localIntegration(),
        // 3. 内联对象
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });

查看集成 API 参考资料，了解所有不同的集成编写方式。

安装 NPM 包

段落标题 安装 NPM 包

使用包管理器安装 NPM 包集成，然后手动更新 astro.config.mjs。

例如，安装 @astrojs/sitemap 集成：

  1. 使用你偏好的包管理器将集成安装到项目依赖中：

    Terminal window
    npm install @astrojs/sitemap

  2. 将集成导入到你的 astro.config.mjs 文件，并将其连同任何配置选项添加到你的 integrations[] 数组中：

    astro.config.mjs
    import { defineConfig } from 'astro/config';
    import sitemap from '@astrojs/sitemap';
    

    export default defineConfig({
      // ...
      integrations: [sitemap()],
      // ...
    });

    请注意，不同的集成可能有不同的配置设置。阅读每个集成的文档，并将任何必要的配置选项应用到 astro.config.mjs 中你所选择的集成上。

自定义选项

段落标题 自定义选项

集成几乎都是以工厂函数的形式编写的，并返回真实的集成对象。这使得你可以通过向工厂函数传递参数和选项定制集成。

integrations: [
  // 示例：用函数参数来定制你的集成
  sitemap({filter: true})
]

切换集成

段落标题 切换集成

你可以切换集成启用状态，而不用担心遗留的 undefined 和布尔值问题，Astro 会自动忽略假值的集成。

integrations: [
  // 示例：在 Windows 上跳过网站地图的构建
  process.platform !== 'win32' && sitemap()
]

更新集成

段落标题 更新集成

要同时更新所有官方集成，运行 @astrojs/upgrade 命令。它会把 Astro 和所有官方集成更新到最新版本。

自动更新

段落标题 自动更新
Terminal window
# 同时升级 Astro 和官方集成到最新版本
npx @astrojs/upgrade

手动更新

段落标题 手动更新

要手动更新一个或多个集成，使用你的包管理器对应的命令。

Terminal window
# 示例：升级 React 和 Tailwind 集成
npm install @astrojs/react@latest @astrojs/tailwind@latest

移除集成

段落标题 移除集成

要移除某个集成，首先从你的项目中卸载它

Terminal window
npm uninstall @astrojs/react

接下来，从 astro.config.* 文件中移除该集成：

astro.config.mjs
import { defineConfig } from 'astro/config';


import react from '@astrojs/react';


export default defineConfig({
  integrations: [
    react()
  ]
});

寻找更多集成

段落标题 寻找更多集成

你可以在 Astro 集成目录中找到许多由社区开发的集成。点击链接查看详细的使用和配置说明。

构建自己的集成

段落标题 构建自己的集成

Astro 的集成 API 受到 Rollup 和 Vite 的启发，其设计使任何曾经写过 Rollup 或 Vite 插件的人都感到熟悉。

查看集成 API，了解集成的作用以及如何自己编写一个集成。