Skip to content

添加集成

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

¥Astro integrations add new functionality and behaviors for your project with only a few lines of code. You can use an official integration, integrations built by the community or even build a custom integration yourself.

集成可以…

¥Integrations can…

  • 使用 renderer 解锁 React、Vue、Svelte、Solid 和其他流行的 UI 框架。

  • 使用 固态继电器适配器 启用按需渲染。

  • 只需几行代码即可集成 Tailwind 和 Partytown 等工具。

  • 向你的项目添加新功能，例如自动站点地图生成。

  • 编写与构建过程、开发服务器等钩子的自定义代码。

官方集成

标题部分 官方集成

¥Official Integrations

以下集成由 Astro 维护。

¥The following integrations are maintained by Astro.

前端框架

SSR 适配器

其他集成

自动集成设置

标题部分 自动集成设置

¥Automatic Integration Setup

Astro 包含一个 astro add 命令来自动设置官方集成。使用此命令还可以添加几个社区插件。请检查每个集成自己的文档，以了解是否支持 astro add，或者是否必须使用 手动安装。

¥Astro includes an astro add command to automate the setup of official integrations. Several community plugins can also be added using this command. Please check each integration’s own documentation to see whether astro add is supported, or whether you must install manually.

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

¥Run the astro add command using the package manager of your choice and our automatic integration wizard will update your configuration file and install any necessary dependencies.

终端窗口
npx astro add react

甚至可以同时添加多个集成！

¥It’s even possible to add multiple integrations at the same time!

终端窗口
npx astro add react tailwind partytown

手动安装

标题部分 手动安装

¥Manual Installation

Astro 集成始终通过 astro.config.mjs 文件中的 integrations 属性添加。

¥Astro integrations are always added through the integrations property in your astro.config.mjs file.

将集成导入到 Astro 项目中的常用方法有以下三种：

¥There are three common ways to import an integration into your Astro project:

  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. Imported from an installed npm package
        installedIntegration(),
        // 2. Imported from a local JS file
        localIntegration(),
        // 3. An inline object
        {name: 'namespace:id', hooks: { /* ... */ }},
      ]
    });

查看 集成 API 参考以了解编写集成的所有不同方法。

¥Check out the Integration API reference to learn all of the different ways that you can write an integration.

安装 NPM 包

标题部分 安装 NPM 包

¥Installing an NPM package

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

¥Install an NPM package integration using a package manager, and then update astro.config.mjs manually.

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

¥For example, to install the @astrojs/sitemap integration:

  1. Install the integration to your project dependencies using your preferred package manager:

    终端窗口
    npm install @astrojs/sitemap

  2. Import the integration to your astro.config.mjs file, and add it to your integrations[] array, along with any configuration options:

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

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

    Note that different integrations may have different configuration settings. Read each integration’s documentation, and apply any necessary config options to your chosen integration in astro.config.mjs.

自定义选项

标题部分 自定义选项

¥Custom Options

集成几乎总是被编写为返回实际集成对象的工厂函数。这使你可以将参数和选项传递给工厂函数，为你的项目自定义集成。

¥Integrations are almost always authored as factory functions that return the actual integration object. This lets you pass arguments and options to the factory function that customize the integration for your project.

integrations: [
  // Example: Customize your integration with function arguments
  sitemap({filter: true})
]

切换集成

标题部分 切换集成

¥Toggle an Integration

虚假集成将被忽略，因此你可以打开和关闭集成，而不必担心旧版的 undefined 和布尔值。

¥Falsy integrations are ignored, so you can toggle integrations on & off without worrying about left-behind undefined and boolean values.

integrations: [
  // Example: Skip building a sitemap on Windows
  process.platform !== 'win32' && sitemap()
]

升级集成

标题部分 升级集成

¥Upgrading Integrations

要一次性升级所有官方集成，请运行 @astrojs/upgrade 命令。这会将 Astro 和所有官方集成升级到最新版本。

¥To upgrade all official integrations at once, run the @astrojs/upgrade command. This will upgrade both Astro and all official integrations to their latest versions.

自动升级

标题部分 自动升级

¥Automatic Upgrading

终端窗口
# Upgrade Astro and official integrations together to latest
npx @astrojs/upgrade

手动升级

标题部分 手动升级

¥Manual Upgrading

要手动升级一个或多个集成，请使用适合你的包管理器的命令。

¥To upgrade one or more integrations manually, use the appropriate command for your package manager.

终端窗口
# Example: upgrade React and Tailwind integrations
npm install @astrojs/react@latest @astrojs/tailwind@latest

删除集成

标题部分 删除集成

¥Removing an Integration

  1. To remove an integration, first uninstall the integration from your project.

    终端窗口
    npm uninstall @astrojs/react

  2. Next, remove the integration from your astro.config.* file:

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

    import react from '@astrojs/react';
    

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

寻找更多集成

标题部分 寻找更多集成

¥Finding More Integrations

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

¥You can find many integrations developed by the community in the Astro Integrations Directory. Follow links there for detailed usage and configuration instructions.

构建你自己的集成

标题部分 构建你自己的集成

¥Building Your Own Integration

Astro 的集成 API 受到 Rollup 和 Vite 的启发，其设计初衷是让以前编写过 Rollup 或 Vite 插件的人感到熟悉。

¥Astro’s Integration API is inspired by Rollup and Vite, and designed to feel familiar to anyone who has ever written a Rollup or Vite plugin before.

查看 集成 API 参考，了解集成可以做什么以及如何自己编写集成。

¥Check out the Integration API reference to learn what integrations can do and how to write one yourself.

Astro 中文网 - 粤ICP备13048890号