Skip to content

Latest commit

 

History

History
268 lines (212 loc) · 7.39 KB

integrations-guide.mdx

File metadata and controls

268 lines (212 loc) · 7.39 KB
Raw
title i18nReady
使用集成
true

import IntegrationsNav from '/components/IntegrationsNav.astro'; import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro'

import { Steps } from '@astrojs/starlight/components'

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

集成能够...

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

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

官方集成

以下集成由 Astro 维护。

自动集成设置

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

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

```shell npx astro add react ``` ```shell pnpm astro add react ``` ```shell yarn astro add react ```

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

```shell npx astro add react tailwind partytown ``` ```shell pnpm astro add react tailwind partytown ``` ```shell yarn astro add react tailwind partytown ```

:::note[处理集成依赖] 如果你在添加集成后看到 "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. 使用你偏好的包管理器将集成安装到项目依赖中： ```shell npm install @astrojs/sitemap ``` ```shell pnpm add @astrojs/sitemap ``` ```shell yarn add @astrojs/sitemap ```

  1. 将集成导入到你的 astro.config.mjs 文件，并将其连同任何配置选项添加到你的 integrations[] 数组中：

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

自动更新

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

手动更新

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

```shell # 示例：升级 React 和 Tailwind 集成 npm install @astrojs/react@latest @astrojs/tailwind@latest ``` ```shell # 示例：升级 React 和 Tailwind 集成 pnpm add @astrojs/react@latest @astrojs/tailwind@latest ``` ```shell # 示例：升级 React 和 Tailwind 集成 yarn add @astrojs/react@latest @astrojs/tailwind@latest ```

移除集成

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

```shell npm uninstall @astrojs/react ``` ```shell pnpm remove @astrojs/react ``` ```shell yarn remove @astrojs/react ```

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

import { defineConfig } from 'astro/config';

import react from '@astrojs/react';

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

寻找更多集成

你可以在 Astro 集成目录中找到许多由社区开发的集成。点击链接查看详细的使用和配置说明。

构建自己的集成

Astro 的集成 API 受到 Rollup 和 Vite 的启发，其设计使任何曾经写过 Rollup 或 Vite 插件的人都感到熟悉。

查看集成 API，了解集成的作用以及如何自己编写一个集成。