首页 / Astro 教程 / 集成前端框架总览

← 上一篇 下一篇 →
Astro 教程

集成前端框架总览

本教程共 56 篇 · 第 28 篇 · 更新于 2026-08-07 · 约 8 分钟阅读

AstroAstro 教程集成ReactVueSveltePreactSolidJS

本节目标：了解 Astro 怎么在不放弃原有框架偏好的前提下接入 React、Vue 等，知道「集成」是什么、五大官方集成分别是什么。

什么是集成

你可能已经会写 React 或 Vue 了，舍不得扔掉。Astro 不强求你改写，它用「集成（integration）」把喜欢的框架接进来，让你照样写熟悉的组件。

集成可以理解成「官方插件」。装上之后，Astro 就认得这种框架的组件文件，能渲染它、也能在浏览器里给它水合。Astro 社区里集成非常多：图片优化、站点地图、MDX 都是集成。

本章只讲「前端框架集成」这一类。后两章会分别手把手接 React，以及 Vue / Svelte / Preact / Solid 的安装要点。

五大官方框架集成

Astro 对下面这些框架提供官方集成，开箱即用：

  • @astrojs/react —— 接入 React
  • @astrojs/preact —— 接入 Preact（API 和 React 几乎一样，但体积只有约 3kB）
  • @astrojs/svelte —— 接入 Svelte
  • @astrojs/vue —— 接入 Vue 3
  • @astrojs/solid-js —— 接入 SolidJS

除此之外，官方还维护了一个 AlpineJS 集成，社区里也有 Angular、Qwik、Elm 等第三方集成，可以在集成目录里找到。

Note

文件后缀就是 Astro 区分框架的依据：.jsx / .tsx 通常是 React / Preact / Solid，.svelte 是 Svelte，.vue 是 Vue。装了对应集成，Astro 才认得它们。

怎么安装一个集成

绝大多数官方集成都能用 astro add 命令一键装好，它会自动改好配置文件。以 React 为例，在项目目录里跑：

# npm
npx astro add react
# pnpm
pnpm astro add react
# yarn
yarn astro add react

跑的时候按提示确认即可。如果一键安装出问题，也可以手动装包再改 astro.config.mjs，具体步骤后面章节会展开。

装好后，集成会出现在配置文件的 integrations 数组里：

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

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

框架组件怎么用

装好集成后，框架组件就能像 Astro 组件一样用了。它们可以一起放在 /src/components，也可以按你的习惯随便组织。

用法就三步：在 Astro 的脚本区用相对路径 import 进来；在模板里像普通标签一样放；需要交互就加 client:* 指令。

---
import MyReactComponent from '../components/MyReactComponent.jsx';
---

<html>
  <body>
    <h1>直接在 Astro 里用 React 组件！</h1>
    <MyReactComponent />
  </body>
</html>

默认情况下，框架组件只在服务端渲染成静态 HTML。这对「不需要交互、纯当模板」的组件很有用，也避免了发多余 JS。

Astro 组件和框架组件的区别

有个关键点要记牢：Astro 组件本身不能水合。它是纯 HTML 模板，没有客户端运行时。如果你给一个 .astro 组件加 client: 指令，会直接报错。

想发 JS 到浏览器，有两个办法：用水合框架组件，或者在 Astro 组件模板里写 <script> 标签，让那段 JS 在全局作用域执行。

反过来，框架组件「变成岛屿」后，必须用那个框架自己的语法写，只能 import 它自己的包。你不能在 .jsx 或 .svelte 文件里 import .astro 组件。

不过，你可以用插槽（slot）模式，在 .astro 文件里，把 Astro 组件生成的静态内容当作子内容传给框架组件。

---
import MyReactComponent from '../components/MyReactComponent.jsx';
import MyAstroComponent from '../components/MyAstroComponent.astro';
---

<MyReactComponent>
  <MyAstroComponent slot="name" />
</MyReactComponent>

可以在一页里混用多个框架

这是 Astro 很有意思的一点：同一个页面里，React、Vue、Svelte 能同时存在。Astro 靠文件后缀判断各自怎么渲染。

---
import MyReactComponent from '../components/MyReactComponent.jsx';
import MySvelteComponent from '../components/MySvelteComponent.svelte';
import MyVueComponent from '../components/MyVueComponent.vue';
---

<div>
  <MySvelteComponent />
  <MyReactComponent />
  <MyVueComponent />
</div>

当两个框架用了相同后缀（比如 React 和 Preact 都是 .jsx），Astro 分不清谁是谁，就需要在配置里用 include 指定哪些文件归哪个框架。单个 JSX 框架时不用管。

什么时候该用框架组件

不是所有交互都要搬框架。下面这些情况，框架组件更合适：

  • 组件内部状态复杂，比如带计数、表单校验、标签页切换。
  • 你手上已有现成的 React / Vue 组件，不想重写。
  • 团队本来就主用某个框架，想保持一致。

什么时候不该用

反过来，这些场景其实用不着框架：

  • 只是给页面加一段点击、滚动的小逻辑。在 .astro 里写 <script> 就够，零框架负担。
  • 纯展示、不需要交互的内容。默认静态渲染最轻最快。
  • 整站都是静态文章、没有任何动态部件。那根本不用装任何框架集成。

性能上的提醒

接入框架集成本身不会拖慢网站。慢的是「水合了多少 JS」。每加一个客户端岛屿，浏览器就要下载对应框架运行时加组件代码。

所以原则还是那句：能静态就静态，必须交互才加 client:* 指令。Astro 把决定权交给你，省不省 JS 看你怎么用。

五个框架怎么挑

  • React：生态最大，组件最多，适合已有 React 积累。
  • Vue：上手平缓，模板写法直观，国内资料多。
  • Svelte：编译期优化，运行时极小，写法简洁。
  • Preact：API 兼容 React，体积仅约 3kB，想轻量又不想换写法就选它。
  • SolidJS：细粒度响应式，性能强，适合复杂交互。

这几个官方集成用法几乎一样，区别主要在安装配置细节。后面两章逐一演示。

集成背后的原理

你或许好奇：Astro 怎么认得 .jsx、.vue 这些文件？答案就是集成。集成本质上是一段配置，告诉 Astro 的构建工具（Vite）「遇到这类文件，用对应框架的编译器处理」。

装了 React 集成，Astro 才知道把 .jsx 交给 React 的编译器；装了 Vue 集成，才知道 .vue 怎么编译。没装，Astro 看到这些文件会直接报错或当成普通文件。

这也解释了为什么集成「装一次、全局生效」。它不是给某个页面装的，而是给整个项目的构建流程装的。你在 astro.config.mjs 里配好一次，所有页面都能用。

和「直接用框架建站」的区别

有人会问：那我直接建一个 React 项目不也一样？差别在于默认值。纯 React 项目默认整站是个大 JS 应用，所有内容都要在客户端渲染、水合。Astro 反过来，默认全是静态 HTML，只把你要交互的少数部分变成岛屿。

所以同样的 React 组件，放进 Astro 后，大部分页面依然是零 JS 的静态页。这对内容型网站（博客、文档、官网）是巨大优势：内容多、交互少，正好命中 Astro 的甜区。

小结

集成是 Astro 接入各大框架的「桥」。五大官方集成覆盖 React、Preact、Svelte、Vue、SolidJS。下一章我们用 React 做完整示例；再下一章快速过一遍另外四个框架的安装要点。

上一篇
客户端指令 client:* 详解
下一篇
React 框架集成示例