使用集成

Astro 集成（Integrations） 只需要几行代码就可以为你的项目添加新的功能和行为。你可以使用官方集成、社区构建的集成或者甚至自己构建一个自定义集成。

集成可以…

• 通过渲染器解锁 React、Vue、Svelte、Solid 以及其他热门 UI 框架。
• 通过 SSR 适配器 启用按需渲染。
• 仅需几行代码即可集成 MDX、Partytown 等工具。
• 为你的项目添加新功能，比如自动生成站点地图（sitemap）。
• 编写接入构建流程、开发服务器等的自定义代码。

集成目录

在我们的集成目录中浏览和搜索数百种官方和社区的集成。查找可以添加到你的 Astro 项目的包，用于身份验证、分析、性能、搜索引擎优化（SEO）、无障碍、用户界面、开发者工具等。

官方集成

以下集成由 Astro 维护。

UI 框架

• 

  @astrojs/alpinejs

• 

  @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

自动配置集成

Astro 包含一个 astro add 命令，可以自动设置官方集成。一些社区插件也可以通过该命令添加。请查看每个集成的官方文档，确认是否支持 astro add，或者必须手动安装。

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

npm

npx astro add react

pnpm

pnpm astro add react

Yarn

yarn astro add react

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

npm

npx astro add react sitemap partytown

pnpm

pnpm astro add react sitemap partytown

Yarn

yarn astro add react sitemap partytown

处理集成依赖项

如果你在添加集成后看到任何类似于 Cannot find package '[package-name]' 的警告，说明你的包管理器可能没有安装同伴依赖（Peer dependencies）。要安装这些缺少的包，运行以下命令：

npm

npm install [package-name]

pnpm

pnpm add [package-name]

Yarn

yarn add [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. 从一个已安装的包中导入
       installedIntegration(),
       // 2. 从本地 JS 文件导入
       localIntegration(),
       // 3. 内联对象
       { name: 'namespace:id', hooks: { /* ... */ } },
     ]
   });

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

安装 npm 包

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

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

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

   npm

   npm install @astrojs/sitemap

   pnpm

   pnpm add @astrojs/sitemap

   Yarn

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

启用/禁用集成

假值（Falsy）集成会被忽略，因此你可以启用/禁用集成，而无需担心残留的 undefined 和布尔值。

integrations: [
  // 示例：在 Windows 上跳过生成站点地图
  process.platform !== 'win32' && sitemap()
]

升级集成

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

自动升级

npm

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

pnpm

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

Yarn

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

手动升级

使用适用于你的包管理器的命令来手动升级一个或多个集成。

npm

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

pnpm

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

Yarn

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

移除集成

1. 要移除某个集成，首先从你的项目中卸载该集成。

   npm

   npm uninstall @astrojs/react

   pnpm

   pnpm remove @astrojs/react

   Yarn

   yarn remove @astrojs/react

2. 接下来从你的 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 参考文档来了解集成能做什么以及如何自行编写集成。

将你的集成发布到 npm

发布一个 Astro 组件是在多个项目中复用你现有成果，并向广大 Astro 社区分享的绝佳方式。Astro 组件可以像其他任何 JavaScript 包一样，直接发布到 npm 以及从 npm 安装。

正在寻找灵感？查看我们从 Astro 社区精选的一些主题和组件。你也可以搜索 npm 来查看完整的公共目录。

不想从零开始？

查看 Astro 社区组件模板，获取社区支持的开箱即用模板！

快速开始

要快速开始开发你的组件，你可以使用一个已经配置好的模板。

npm

# 在一个新目录初始化 Astro 组件模板
npm create astro@latest my-new-component-directory -- --template component

pnpm

# 在一个新目录初始化 Astro 组件模板
pnpm create astro@latest my-new-component-directory -- --template component

Yarn

# 在一个新目录初始化 Astro 组件模板
yarn create astro my-new-component-directory --template component

创建一个包

前提条件

在开始之前，了解以下基础知识会有所帮助：

• Node 模块
• 包清单（package.json）
• 工作区（Workspaces）

要创建一个新包需要将你的开发环境配置为在项目中使用工作区。这允许你在开发组件的同时，运行一个 Astro 工作副本。

• 文件夹my-new-component-directory/

  • 文件夹demo/

    • … 用于测试和演示
  • package.json
  • 文件夹packages/

    • 文件夹my-component/

      • index.js
      • package.json
      • … 该包使用的其他文件

这个名为 my-project 的示例中创建了一个项目，该项目包含一个名为 my-component 的单独包，以及一个 demo/ 目录用于测试和演示组件。

这在项目根目录的 package.json 中进行配置：

{
  "name": "my-project",
  "workspaces": ["demo", "packages/*"]
}

在这个示例中，可以从 packages 目录中同时开发多个包。这些包也可以被 demo 引用，你可以在该目录下安装一个 Astro 的工作副本。

npm

npm create astro@latest demo -- --template minimal

pnpm

pnpm create astro@latest demo -- --template minimal

Yarn

yarn create astro demo --template minimal

组成你的个人包的初始文件有两个：package.json 和 index.js。

package.json

包目录中的 package.json 包含与你的包相关的所有信息，包括其描述、依赖项、以及所有其他的包元数据。

{
  "name": "my-component",
  "description": "Component description",
  "version": "1.0.0",
  "homepage": "https://github.com/owner/project#readme",
  "type": "module",
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  },
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"],
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

description

关于你的组件的简短描述，用于帮助其他人了解其功能。

{
  "description": "An Astro Element Generator"
}

type

Node.js 和 Astro 用于解析你的 index.js 文件的模块格式。

{
  "type": "module"
}

使用 "type": "module"，这样你的 index.js 可以被用作入口文件，通过 import 和 export 使用。

homepage

项目主页的链接。

{
  "homepage": "https://github.com/owner/project#readme"
}

这是引导用户访问你的项目的在线演示、文档或主页的绝佳方式。

exports

包按名称导入时的入口。

{
  "exports": {
    ".": "./index.js",
    "./astro": "./MyAstroComponent.astro",
    "./react": "./MyReactComponent.jsx"
  }
}

在这个示例中，导入 my-component 会使用 index.js，而导入 my-component/astro 或 my-component/react 会分别使用 MyAstroComponent.astro 或 MyReactComponent.jsx。

files

一项可选的优化，用于从分发给用户的打包文件中排除不必要的文件。请注意只有在此处列出的文件才会被包含在你的包中，因此如果你添加或修改了包运行所需的文件，必须相应地更新此列表。

{
  "files": ["index.js", "MyAstroComponent.astro", "MyReactComponent.jsx"]
}

keywords

与你的组件相关的一组关键词，用于帮助其他人在 npm 以及其他搜索目录中找到你的组件。

添加 astro-component、astro-integration 或 withastro 作为特殊关键词以最大化其在 Astro 生态系统中的可发现性。

{
  "keywords": ["astro-component", "withastro", "... etc", "... etc"]
}

提示

我们的集成库也会使用关键词！查看下方可获取我们在 npm 中搜索的关键词列表。

---

index.js

导入你的包时所使用的主要入口。

export { default as MyAstroComponent } from './MyAstroComponent.astro';
export { default as MyReactComponent } from './MyReactComponent.jsx';

这允许你将多个组件打包到同一个接口中。

示例：使用命名导入

---
import { MyAstroComponent } from 'my-component';
import { MyReactComponent } from 'my-component';
---
<MyAstroComponent />
<MyReactComponent />

示例：使用命名空间导入

---
import * as Example from 'example-astro-component';
---
<Example.MyAstroComponent />
<Example.MyReactComponent />

示例：使用单独导入

---
import MyAstroComponent from 'example-astro-component/astro';
import MyReactComponent from 'example-astro-component/react';
---
<MyAstroComponent />
<MyReactComponent />

---

开发你的包

Astro 没有用于开发的“包模式”。相反，你应该在你的项目中使用一个示例项目来开发和测试你的包。这可以是一个用于开发的私有网站，或你的包的公共演示/文档网站。

如果你正在从一个已有的项目中提取组件，你甚至可以继续使用该项目开发提取出来的组件。

测试你的组件

Astro 目前并未内置测试运行工具。（如果你有兴趣为此提供帮助，加入我们的 Discord 社区）

同时，我们目前推荐的测试方案是：

1. 在你的 demo/src/pages 目录下新建一个 fixtures 目录。

2. 为每个你想要运行的测试添加一个新页面。

3. 每个页面都应包含你想要测试的一些不同的组件用法。

4. 运行 astro build 来构建你的测试页面，然后将 dist/__fixtures__/ 目录的输出与你的预期进行对比。

   • 文件夹my-project/demo/src/pages/__fixtures__/

     • test-name-01.astro
     • test-name-02.astro
     • test-name-03.astro

发布你的组件

准备好你的包后，你可以通过使用 npm publish 命令来发布到 npm。如果失败，请确保你已经通过 npm login 登录，并且你的 package.json 是正确的。如果成功，就大功告成了。

注意 Astro 包没有 构建 步骤。Astro 原生支持的任意文件类型，例如 .astro、.ts、.jsx、和 .css，都可以直接发布，无需构建步骤。

如果你需要 Astro 未原生支持的其他文件类型，就在你的包中添加一个构建步骤。这项进阶练习留待你自行完成。

集成库

通过将你的集成添加到我们的集成库中来分享你的成果！

提示

需要帮助构建你的集成，或者只是想认识其他集成开发者？我们在 Discord 服务器上有专门的 #integrations 频道。欢迎来打个招呼！

package.json 数据

该库每周自动更新，会拉取所有发布到 npm 并带有 astro-component、astro-integration 或 withastro 的包。

集成库会从你的 package.json 中读取 name、description、repository 和 homepage 数据。

头像是在库中突出展示你品牌的绝佳机会！一旦你的包发布后，你可以提交一个 GitHub issue 并附上你的头像，我们会将其添加到你的列表中。

提示

需要覆盖我们的库从 npm 中读取的信息？没问题！提交一个 issue 并附上更新后的信息，我们会确保改用自定义的 name、description 或 homepage。

分类

除了必需的 astro-component、astro-integration 或 withastro 关键词以外，特定的关键词也会被用来自动分类包。包含以下任一关键词都会将你的集成添加到集成库中对应的分类。

category	keywords
无障碍（Accessibility）	a11y, accessibility
适配器（Adapters）	astro-adapter
分析（Analytics）	analytics
CSS + UI	css, ui, icon, icons, renderer
框架（Frameworks）	renderer
内容加载器（Content Loaders）	astro-loader
图像与媒体（Images + Media）	media, image, images, video, audio
性能与 SEO（Performance + SEO）	performance, perf, seo, optimization
开发工具栏（Dev Toolbar）	devtools, dev-overlay, dev-toolbar
工具（Utilities）	tooling, utils, utility

不包含对应任何分类关键词的包将显示为 未分类（Uncategorized）。

分享

我们鼓励你分享自己的作品，并且我们很乐于见到才华横溢的 Astro 同伴们创造的成果。来 Discord 与我们分享你的成果，或在推文中提到 @astrodotbuild！