Vue / Svelte / Preact / Solid 集成

共同的安装方式

四个集成都用同一套思路：先 astro add，或手动装包再改 astro.config.mjs。下面每个框架给出各自的命令和最简配置，细节差异单独说。

Vue（@astrojs/vue）

Vue 3 的集成。一键安装：

npx astro add vue
# 或 pnpm astro add vue / yarn astro add vue

手动安装：

npm install @astrojs/vue
# 若启动报 Cannot find package 'vue'，再装：npm install vue

配置：

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

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

Vue 集成支持几个可选配置，比如 appEntrypoint（扩展 Vue 的 app 实例、用自定义插件）、jsx（开启 Vue JSX 渲染）、devtools（开发环境开启 Vue DevTools）。

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

export default defineConfig({
  integrations: [
    vue({
      appEntrypoint: '/src/pages/_app', // 自定义插件入口
      jsx: true,                         // 支持 Vue JSX
      devtools: true,                   // 开发期 DevTools
    }),
  ],
});

appEntrypoint 指向的文件，默认导出一个接收 Vue App 实例的函数，方便你 app.use(插件)：

import type { App } from 'vue';
import i18nPlugin from 'my-vue-i18n-plugin';

export default (app: App) => {
  app.use(i18nPlugin);
};

Svelte（@astrojs/svelte）

当前集成面向 Svelte 5。若要用 Svelte 3 / 4，请装 @astrojs/svelte@5。

npx astro add svelte
# 或 pnpm astro add svelte / yarn astro add svelte

手动安装后，除了改配置，还要在项目根目录新建 svelte.config.js：

import { vitePreprocess } from '@astrojs/svelte';

export default {
  preprocess: vitePreprocess(),
};

配置：

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

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

如果你在 Svelte 文件里用了 SCSS 或 Stylus，这个 svelte.config.js 里的 vitePreprocess 会负责预处理。跑 astro add svelte 时它会自动帮你建好。

Preact（@astrojs/preact）

Preact 是个轻量库，API 和 React 几乎一样，但包只有约 3kB。如果你用过 React，会非常顺手。甚至能用 compat 选项直接渲染很多 React 组件。

npx astro add preact
# 或 pnpm astro add preact / yarn astro add preact

手动安装后，同样要改 tsconfig.json 的 JSX 设置，不过 jsxImportSource 换成 preact：

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "preact"
  }
}

配置：

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

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

Preact 最有用的选项是 compat：开启后无需安装 React 那套大库，就能渲染 React 组件，也允许在 Preact 组件里 import React 组件。

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

export default defineConfig({
  integrations: [preact({ compat: true })],
});

要是你 import 的是第三方 React 组件库，想把它内部的 react / react-dom 替换成 preact/compat，可以在 package.json 里用 overrides：

{
  "overrides": {
    "react": "npm:@preact/compat@latest",
    "react-dom": "npm:@preact/compat@latest"
  }
}

此外还有 babel（给 Preact 的 Vite 插件传额外 Babel 配置）和 devtools（开发期开启 Preact DevTools）两个选项，按需使用。

SolidJS（@astrojs/solid-js）

npx astro add solid
# 或 pnpm astro add solid / yarn astro add solid

手动安装后，tsconfig.json 的 JSX 设置又不一样，jsx 用 preserve、jsxImportSource 用 solid-js：

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"],
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "solid-js"
  }
}

配置：

import { defineConfig } from 'astro/config';
import solidJs from '@astrojs/solid-js';

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

Solid 有个贴心设计：服务端渲染和带水合的组件，会自动被包进顶层的 Suspense 边界，用 renderToStringAsync 渲染。所以用 Solid 的 createResource 在服务端取异步数据，初始 HTML 里就已经包含结果，不用你手动加 Suspense。

function CharacterName() {
  const [name] = createResource(() =>
    fetch('https://swapi.dev/api/people/1')
      .then((r) => r.json())
      .then((d) => d.name)
  );

  return (
    <>
      <h2>Name:</h2>
      <div>{name()}</div>
    </>
  );
}

Solid 也支持 devtools 选项，需在项目依赖里再加 solid-devtools。

多 JSX 框架的通用配置

React、Preact、Solid 都是 .jsx / .tsx。多个共存时，靠 include 指明目录，这部分在 React 那章已经演示过，这里不再贴重复代码。一句话：把不同框架组件分目录放，再在各自集成里 include 对应目录即可。

同一个功能，四种写法

为了让差异更直观，下面用「计数器」分别写四个框架的写法。重点看语法风格，不用纠结细节。

Vue（<script setup>）：

<script setup>
import { ref } from 'vue';
const count = ref(0);
</script>

<template>
  <button @click="count++">点了 {{ count }} 次</button>
</template>

Svelte：

<script>
  let count = 0;
</script>

<button on:click={() => count++}>点了 {count} 次</button>

Preact（和 React 几乎一致）：

import { useState } from 'preact/hooks';

export default function Counter() {
  const [count, setCount] = useState(0);
  return <button onClick={() => setCount(count + 1)}>点了 {count} 次</button>;
}

SolidJS（细粒度响应式）：

import { createSignal } from "solid-js";

export default function Counter() {
  const [count, setCount] = createSignal(0);
  return <button onClick={() => setCount(count() + 1)}>点了 {count()} 次</button>;
}

在 Astro 页面里，它们都这样用：import 进来，加 client:* 指令即可。你也可以在同一页同时用这四个，只要它们的文件后缀和 include 配置对得上。

各自的小提醒

• Vue：若用 JSX 模板或自定义元素，记得在 vue({...}) 里配 jsx 或 template.compilerOptions。
• Svelte：SCSS/Stylus 要写 svelte.config.js 的 vitePreprocess；Svelte 5 是当前默认。
• Preact：compat: true 能直接吃 React 组件，体积优势明显。
• SolidJS：异步数据用 createResource，默认就包了 Suspense，不用手动加。

一张表快速对比

框架	集成包	关键配置	适合谁
Vue	@astrojs/vue	appEntrypoint / jsx / devtools	熟悉 Vue 模板写法
Svelte	@astrojs/svelte	需 svelte.config.js	想要极小运行时
Preact	@astrojs/preact	compat 兼容 React	想轻量又用 React API
SolidJS	@astrojs/solid-js	tsconfig 用 preserve	复杂响应式交互

先想清楚：真的要四个都装吗

看到四个框架都能接，有人会想一口气全装。但请先问自己：项目里真的会同时用到吗？大多数情况下，一个团队、一个项目只主用一种框架。

只装一个最省心：不用管 include 区分目录，不用怕文件后缀冲突，团队成员也只要懂一种。只有当你的确需要在同一站里混用（比如老代码是 Vue、新模块想用 React）时，才值得同时接多个。

各框架的设计取舍

Vue 走「模板 + 响应式」路线，写起来像在写 HTML，对新手友好，国内社区也很成熟。Svelte 反其道而行，把很多工作放在编译阶段完成，运行时几乎不占地方，最终打包体积很小。

Preact 是 React 的「轻量替身」，API 几乎一模一样，但体积小到只有约 3kB。老 React 项目想瘦身，用 compat 选项基本能无缝切换。SolidJS 则主打细粒度响应式，状态变了只更新相关那一点 DOM，性能在复杂交互里很出色。

选哪个没有绝对答案，看团队熟悉度和项目需求。好消息是，它们在 Astro 里的用法高度一致：装包、改配置、import、加 client:* 指令。学会一个，其余触类旁通。

装好之后怎么验证

集成装完、配置改好，最快的验证方式是建一个最小的框架组件，加 client:load 丢到页面上，跑起开发服务器看它能否交互。能点击、能响应，说明集成生效。

如果浏览器里组件一片空白或报错，先检查两件事：对应框架包是否真的装上了（比如 vue、svelte、solid-js）；多 JSX 框架时 include 目录是否指对。这两类问题占了新手踩坑的大多数。

各框架常见踩坑

把四个框架最容易翻车的地方列成一张清单，照着查能省不少时间：

• Vue：组件不渲染，先看 vue 包有没有装；用了 JSX 模板却没在 vue({ jsx: true }) 里开，语法会报错。
• Svelte：用了 SCSS/Stylus 却没建 svelte.config.js（或里头的 vitePreprocess 没配），样式预处理会失败；Svelte 5 是新默认，老项目要显式装 @astrojs/svelte@5。
• Preact：想直接吃 React 组件却忘了 compat: true，结果 import 的 React 组件跑不起来。
• SolidJS：tsconfig 的 jsx 必须写 preserve、且 jsxImportSource 是 solid-js；写错就编译不过。

还有一个共通坑：忘了加 client:* 指令。不管哪个框架，没有指令就不会发 JS，组件只会是静态 HTML，自然「点了没反应」。

写在最后

四个框架集成的「安装步骤」看着多，其实套路完全一样：跑一条 astro add，或在 astro.config.mjs 的 integrations 里加一行。真正的差异只在少数配置项：Svelte 多一个 svelte.config.js，Preact 有 compat 兼容 React，Solid 的 tsconfig 写法不同。把这些记住，四个框架你都能轻松接上。

记不住也没关系，官方文档每个集成页都列了完整步骤。本教程只帮你建立「整体图景」，真到用时对着文档抄一遍即可。

版本对应关系

写这篇时各集成版本大致是：Vue v7.0.2、Svelte v9.0.1、Preact v6.0.2、Solid v7.0.2，都能和 Astro 7 配合。版本号会随框架更新而变，但「装包 + 改配置 + 加 client 指令」的主线不会变。真遇到报错，多半是 peer 依赖没装全（比如忘了装 vue、svelte），按终端提示补上即可。

小结

四个框架集成步骤大体一致：装包、改 astro.config.mjs、按需改 tsconfig.json 或 svelte.config.js。差异点记住三处：Svelte 要 svelte.config.js；Preact 有 compat 兼容 React；Solid 的 tsconfig 用 preserve。