添加集成

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 等工具。

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

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

Integrations directory

Browse or search the complete set of hundreds of official and community integrations in our integrations directory. Find packages to add to your Astro project for authentication, analytics, performance, SEO, accessibility, UI, developer tools, and more.

官方集成

Section titled 官方集成

¥Official Integrations

以下集成由 Astro 维护。

¥The following integrations are maintained by Astro.

UI Frameworks

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR Adapters

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

Other integrations

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

自动集成设置

Section titled 自动集成设置

¥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.

npm

npx astro add react

pnpm

pnpm astro add react

Yarn

yarn astro add react

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

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

npm

npx astro add react tailwind partytown

pnpm

pnpm astro add react tailwind partytown

Yarn

yarn astro add react tailwind partytown

Handling integration dependencies

If you see any warnings like Cannot find package '[package-name]' after adding an integration, your package manager may not have installed peer dependencies for you. To install these missing packages, run npm install [package-name].

手动安装

Section titled 手动安装

¥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 包

Section titled 安装 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

   npm install @astrojs/sitemap

   pnpm

   pnpm add @astrojs/sitemap

   Yarn

   yarn add @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

自定义选项

Section titled 自定义选项

¥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})
]

切换集成

Section titled 切换集成

¥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()
]

升级集成

Section titled 升级集成

¥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.

自动升级

Section titled 自动升级

¥Automatic Upgrading

npm

# Upgrade Astro and official integrations together to latest
npx @astrojs/upgrade

pnpm

# Upgrade Astro and official integrations together to latest
pnpm dlx @astrojs/upgrade

Yarn

# Upgrade Astro and official integrations together to latest
yarn dlx @astrojs/upgrade

手动升级

Section titled 手动升级

¥Manual Upgrading

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

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

npm

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

pnpm

# Example: upgrade React and Tailwind integrations
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

Yarn

# Example: upgrade React and Tailwind integrations
yarn add @astrojs/react@latest @astrojs/tailwind@latest

删除集成

Section titled 删除集成

¥Removing an Integration

要删除集成，请首先从项目中卸载该集成

¥To remove an integration, first uninstall the integration from your project

npm

npm uninstall @astrojs/react

pnpm

pnpm remove @astrojs/react

Yarn

yarn remove @astrojs/react

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

¥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()
  ]
});

寻找更多集成

Section titled 寻找更多集成

¥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.

构建你自己的集成

Section titled 构建你自己的集成

¥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.