Question

使用 Astro 集成只需几行代码就能为你的项目添加新的功能和行为。你可以自己编写一个自定义的集成，可以使用官方集成，还可以使用社区内的集成。

集成能够…

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

集成目录

在我们的 集成目录 中浏览或搜索数百个官方和社区集成的完整集成。在这里你找到可以添加到你的 Astro 项目中的包，涵盖了身份验证、分析、性能、SEO、无障碍、UI、开发者工具等场景。

官方集成

以下集成由 Astro 维护。

UI 框架

• 

  @astrojs/alpinejs

• 

  @astrojs/lit

• 

  @astrojs/preact

• 

  @astrojs/react

• 

  @astrojs/solid⁠-⁠js

• 

  @astrojs/svelte

• 

  @astrojs/vue

SSR 适配器

• 

  @astrojs/cloudflare

• 

  @astrojs/netlify

• 

  @astrojs/node

• 

  @astrojs/vercel

其他集成

• 

  @astrojs/db

• 

  @astrojs/markdoc

• 

  @astrojs/mdx

• 

  @astrojs/partytown

• 

  @astrojs/sitemap

• 

  @astrojs/tailwind

自动集成设置

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

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

• npm
• pnpm
• Yarn

npx astro add react

pnpm astro add react

yarn astro add react

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

• npm
• pnpm
• Yarn

npx astro add react tailwind partytown

pnpm astro add react tailwind partytown

yarn astro add react tailwind partytown

处理集成依赖

如果你在添加集成后看到 "Cannot find package '[package-name]' 或其他类似警告，这意味着你的包管理器可能没有安装对等依赖。要安装这些缺失的包，请运行 npm install [package-name]。

手动安装

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 包集成，然后手动更新 astro.config.mjs。

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

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

   • npm
   • pnpm
   • Yarn

   npm install @astrojs/sitemap

   pnpm add @astrojs/sitemap

   yarn add @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 和所有官方集成更新到最新版本。

自动更新

• npm
• pnpm
• Yarn

# 同时升级 Astro 和官方集成到最新版本
npx @astrojs/upgrade

# 同时升级 Astro 和官方集成到最新版本
pnpm dlx @astrojs/upgrade

# 同时升级 Astro 和官方集成到最新版本
yarn dlx @astrojs/upgrade

手动更新

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

• npm
• pnpm
• Yarn

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

# 示例：升级 React 和 Tailwind 集成
pnpm add @astrojs/react@latest @astrojs/tailwind@latest

# 示例：升级 React 和 Tailwind 集成
yarn add @astrojs/react@latest @astrojs/tailwind@latest

移除集成

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

• npm
• pnpm
• Yarn

npm uninstall @astrojs/react

pnpm remove @astrojs/react

yarn remove @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，了解集成的作用以及如何自己编写一个集成。