add-integration

添加 Astro 集成

在 Astro 项目中添加官方或社区集成时使用此技能，包括 UI 框架、样式工具、适配器、内容工具和实用工具。

如果有 astro-best-practices，请结合此技能使用，以遵循性能、无障碍和水合方面的默认做法。

工作流

1. 对集成进行分类

在进行任何更改之前，先确定要添加的内容：

• UI 框架：React、Vue、Svelte、Preact、Solid
• 样式：Tailwind、UnoCSS、Sass、CSS 工具
• 部署适配器：Netlify、Vercel、Cloudflare、Node
• 内容工具：MDX、Markdoc、CMS 集成
• 实用工具：sitemap、Partytown、分析、数据库辅助工具

这决定了更改是否会影响渲染模式、水合、配置结构或构建输出。

2. 优先采用官方 Astro 方式

如果官方集成支持，请使用 astro add：

npx astro add react
npx astro add tailwind
npx astro add netlify

如果集成由社区维护，请使用项目包管理器安装，并手动将其接入 astro.config.*。

完成前，请查阅 Astro 官方文档或集成 README，确认当前设置，尤其是在 Astro 或集成最近更新版本的情况下。

如果项目也在升级 Astro，请同时升级 Astro 和官方集成。对于 Astro 6，在将集成问题视为应用程序错误之前，请确认环境运行的是 Node 22.12.0 或更高版本。

3. 谨慎配置 Astro

编辑 astro.config.* 时：

• 明确添加集成，并保持数组易于阅读
• 仅在适配器或运行时有要求时设置 output
• 除非功能确实需要在请求时执行，否则不要启用服务器输出
• 除非集成文档要求特定顺序，否则保留现有配置顺序

示例：

import { defineConfig } from 'astro/config'
import react from '@astrojs/react'

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

4. 谨慎处理框架组件

添加 React、Vue 或其他 UI 框架时：

• 静态内容优先使用 .astro
• 仅在交互式孤岛中使用框架组件
• 选择满足用户体验要求的最轻量客户端指令

水合指南：

• 对于首屏以下或延迟加载的 UI，使用 client:visible
• 对于非关键增强功能，使用 client:idle
• 仅对需要立即交互的 UI 使用 client:load
• 仅在有意跳过服务器端渲染时使用 client:only

5. 完成周边设置

不要只安装软件包。请检查以下内容：

• 样式表导入或入口文件
• 环境变量
• tailwind.config.* 等配置文件
• 适配器特定的输出要求
• 平台部署设置

对于 Tailwind v4，最低限度的设置通常只需：

@import "tailwindcss";

并从共享布局或入口文件导入该样式表。

6. 验证结果

完成设置后：

• 确认集成已在 astro.config.* 中注册
• 运行适用于该代码库的检查，例如 astro check、astro build 或现有测试套件
• 重大升级 Astro 后，确认部署／运行时环境仍符合适配器要求
• 检查是否存在水合不匹配、样式缺失或适配器／运行时偏差

常见故障模式

• 已安装软件包，但未将其添加到 integrations
• 添加适配器，却没有匹配的 output
• 样式已准备好，但从未导入
• 在使用普通 .astro 组件会更简单的情况下添加了框架组件
• 过度使用 client:load，增加了 JavaScript 开销