集成（Integrations）安装与配置

Astro 之所以”小而全”，靠的是一套叫**集成（integration，可理解为插件）**的机制。集成就是别人写好的功能包，你只要加几行配置，就能给项目装上原本没有的能力——比如让 Astro 支持 React 组件、自动生成站点地图、开启 MDX 写作。本章只讲”集成怎么装、怎么配”这条主线；某个具体集成怎么用，留给对应章节。

集成到底能干什么

集成不是花架子，它能做的事很实在：

• 解锁 React、Vue、Svelte、Solid 等前端框架（靠 renderer 渲染器集成，第 28–30 章）。
• 开启按需渲染（靠 SSR 适配器，第 40 章）。
• 接入 MDX、Partytown 这类工具，只需几行代码。
• 给项目加新功能，比如自动生成 sitemap。
• 写自定义代码，挂在构建流程、开发服务器等”钩子”上。

一句话：Astro 的核心很小，大部分”外围功能”都是靠集成补上的。

官方集成有哪些

Astro 官方维护一批集成，大致分三类：

• 前端框架类：@astrojs/react、@astrojs/vue、@astrojs/svelte、@astrojs/solid-js、@astrojs/preact、@astrojs/alpinejs。
• 适配器类：@astrojs/vercel、@astrojs/netlify、@astrojs/node、@astrojs/cloudflare，用于部署（第 40 章细讲）。
• 其他工具类：@astrojs/mdx、@astrojs/markdoc、@astrojs/partytown、@astrojs/sitemap。

社区还有大量集成，可在 Astro 集成市场（astro.build/integrations）找到。想加某个具体功能，先去那里搜一圈往往最快。

自动安装：astro add

最省事的方式是 astro add 命令。它会帮你装好包，并自动改好 astro.config.mjs，不用手抖改错。

以安装 React 集成为例：

npx astro add react

用 pnpm 或 yarn 也行，效果一样：

pnpm astro add react
yarn astro add react

还能一次装多个，省得反复敲命令：

npx astro add react sitemap partytown

注意：只有官方集成和少数社区插件支持 astro add。装之前先看该集成的文档确认；不支持的，就走下面的手动安装。

手动安装

所有集成最终都通过 astro.config.mjs 里的 integrations 数组接入。常见的集成来源有三种：

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. 从本地文件导入
    localIntegration(),
    // 3. 内联对象
    { name: 'namespace:id', hooks: { /* ... */ } },
  ]
});

装一个 npm 包

以 @astrojs/sitemap 为例，分两步。

第一步，用包管理器把包装进项目依赖：

npm install @astrojs/sitemap
pnpm add @astrojs/sitemap
yarn add @astrojs/sitemap

第二步，在 astro.config.mjs 里导入，并加进 integrations 数组。需要的话把配置项一起传进去：

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

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

不同集成的配置项不一样，务必读该集成自己的文档，再把要用的选项填进 integrations 数组里对应的那一项。

给集成传配置项

集成几乎都是”工厂函数”：你调用它（例如 sitemap()）才返回真正的集成对象。这样设计的好处是，你能传参数来定制它。

integrations: [
  // 用函数参数定制集成
  sitemap({ filter: true })
]

临时开关集成

integrations 数组里只认”真值”。写 false 或 undefined 的项会被直接忽略。利用这点，你可以用表达式灵活地开/关集成，而不用删代码：

integrations: [
  // 在 Windows 上跳过生成 sitemap
  process.platform !== 'win32' && sitemap()
]

升级与移除

想把所有官方集成一次性升到最新，用一条命令，它会把 Astro 和官方集成一起升级：

npx @astrojs/upgrade

只升某一个，就正常用包管理器指定版本：

npm install @astrojs/react@latest @astrojs/partytown@latest

要移除一个集成，先卸载包：

npm uninstall @astrojs/react

再把 astro.config.mjs 的 integrations 数组里对应的那行删掉即可。

想自己写集成？

Astro 的集成 API 受 Rollup 和 Vite 启发，如果你写过这两者的插件会觉得很眼熟。能力范围、写法细节在官方”集成 API 参考”里。社区里很多集成就是把常用逻辑封装后发到 npm 分享——你也可以把自己的组件或集成发上去。这条进阶之路本教程不展开，知道”集成是可扩展的”就够了。

怎么挑一个集成

面对众多集成，挑法很简单：先想清楚”我要补什么能力”。要支持某个前端框架，就找对应的 renderer 集成；要自动生成 sitemap，就找 @astrojs/sitemap；要写 MDX，就找 @astrojs/mdx。Astro 集成市场按功能分类（框架、CMS、图片、性能/SEO、开发工具栏等），搜索比死记名字高效。

挑集成时还有一点：看它的维护状态。优先选官方维护的集成（带 @astrojs/ 前缀），它们跟着 Astro 大版本一起升级，兼容性最稳。社区集成功能可能更花哨，但更新节奏不一定跟得上，装之前翻翻它的更新时间和 Issues，能少踩兼容性的坑。

集成和配置的关系再强调

所有集成的”总入口”都是 astro.config.mjs 的 integrations 数组。无论自动还是手动安装，最终都落到这里。适配器也是数组里的一项，只是它额外需要 output 配合（第 40 章）。理解这一点，你看任何集成的文档都不会慌：步骤无非”装包 → 在数组里加一项 → 必要时传配置”。

常见踩坑

• 忘了在 integrations 里登记：装了包却没加进数组，集成不生效。
• 配置项写错位置：配置是传给工厂函数 xxx() 的参数，不是数组的直接子项。
• 以为 astro add 万能：社区插件很多不支持，得手动装。
• 集成版本和 Astro 版本不匹配：升级用 @astrojs/upgrade 能一起升，最稳。

集成和纯 npm 包有什么不同

有人会问：集成和普通的 npm 包有啥区别？区别在于”约定”。普通 npm 包你要自己 import、自己接线；集成则和 Astro 的构建/开发流程有约定好的钩子，加进 integrations 数组后，Astro 会在特定时机调用它（比如改 Vite 配置、注入 HTML、处理资源）。你也可以把一组功能封装成自己的集成发出去，让别的项目 astro add 就能用。理解”集成 = 与 Astro 生命周期挂钩的插件”，就不会和一般依赖混淆。

小结

集成是 Astro 的插件机制，几行配置就能加新能力。能用 astro add 就别手动；装好后在 astro.config.mjs 的 integrations 数组里登记。集成多是工厂函数，可传参定制；写 false 就能临时关闭。适配器本质上也是一种集成，下一章单独讲它和部署的关系。

下一章我们看适配器：它为什么是按需渲染的硬性前提，又对应哪些部署平台。