Astro Islands 架构师
Astro 的理念是“默认输出 HTML,仅对需要 JS 的部分进行水合”。对于营销、文档和内容为主的站点,它能产生比 React/Next.js 小得多的包体积。核心在于决定哪些组件是静态的,哪些是岛屿(需要交互的组件)。
适用场景
- 营销站点、博客、文档门户——内容为王。
- 从客户端 JS 过重的 Next.js 营销站点迁移。
- 多框架——同时使用 React 组件库与 Vue 或 Svelte 组件。
- 使用 MDX + 类型安全前端数据(frontmatter)进行大量内容创作。
- 无需 SPA 就能实现页面间的视图过渡。
核心能力
页面结构
---
// src/pages/blog/[slug].astro — 前端数据在构建/SSR 时运行
import { getCollection, getEntry } from 'astro:content';
import Layout from '../../layouts/Default.astro';
import Newsletter from '../../components/Newsletter.tsx';
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map((p) => ({ params: { slug: p.slug }, props: { post: p } }));
}
const { post } = Astro.props;
const { Content } = await post.render();
---
<Layout title={post.data.title}>
<h1>{post.data.title}</h1>
<article><Content /></article>
{/* 岛屿 — 只有这个组件会加载 JS */}
<Newsletter client:visible />
</Layout>
--- 定界符内的代码是服务端代码。在 <...> 中,默认输出静态 HTML。带有 client:* 指令的组件将成为岛屿。
客户端指令 — 选择合适的指令
| 指令 | 水合时机 | 用途 |
|---|---|---|
client:load | 页面加载时 | 首屏交互(购物车、搜索)。 |
client:idle | 浏览器空闲时 | 非关键交互(聊天窗口)。 |
client:visible | 滚动到视口时 | 视口下方内容(新闻订阅、评论)。 |
client:media="(min-width: 768px)" | 媒体查询匹配时 | 仅桌面端的小部件。 |
client:only="react" | 跳过 SSR;仅客户端渲染 | 组件初始化需要浏览器 API。 |
client:idle 是大多数非关键岛屿的合适默认值。client:load 是重量级选择,应谨慎使用。
内容集合
// src/content/config.ts
import { defineCollection, z } from 'astro:content';
const blog = defineCollection({
type: 'content', // markdown/MDX 文件
schema: z.object({
title: z.string().max(120),
description: z.string().max(160),
date: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
cover: z.object({ src: z.string(), alt: z.string() }).optional(),
}),
});
export const collections = { blog };
现在,getCollection('blog') 是完全类型安全的。前端数据错误会在构建时失败,而不是在生产环境中暴露。
const posts = (await getCollection('blog'))
.filter((p) => !p.data.draft)
.sort((a, b) => +b.data.date - +a.data.date);
多框架
npx astro add react vue svelte
---
import ReactSearch from '../components/Search.tsx';
import VueChart from '../components/Chart.vue';
import SvelteToggle from '../components/Toggle.svelte';
---
<ReactSearch client:idle />
<VueChart client:visible />
<SvelteToggle client:load />
每个框架的运行时会被单独打包,并且仅在使用它的页面上加载。对于大部分是静态的文档站点,这意味着大多数页面可以不加载任何 React JS。
服务端岛屿(Astro 4+)
<Layout>
<Header />
<PersonalizedRecommendations server:defer>
<p slot="fallback">正在加载推荐内容...</p>
</PersonalizedRecommendations>
<Footer />
</Layout>
server:defer 会立即渲染页面的其余部分,并通过单独的请求流传输延迟组件的 HTML。对于个性化内容,这很有用,否则会强制整个页面进行 SSR。
图像优化
---
import { Image } from 'astro:assets';
import cover from '../assets/cover.jpg';
---
<Image src={cover} alt="封面图片" widths={[400, 800, 1200]} sizes="(max-width: 768px) 400px, 1200px" />
Astro 生成 srcset,使用 Sharp 进行缩放,并仅加载所需尺寸。将图像放在 src/assets/ 下以进行完整优化;public/ 目录下的图像不经过处理。
视图过渡
---
import { ViewTransitions } from 'astro:transitions';
---
<html>
<head>
<ViewTransitions />
</head>
...
</html>
<a href="/about" transition:name="hero">关于我们</a>
无需 SPA 即可实现跨页面过渡。浏览器完成大部分工作;Astro 负责协调元素匹配。
使用组件 MDX
---
title: 我的文章
date: 2026-04-30
---
import Callout from '../../components/Callout.astro';
# {frontmatter.title}
<Callout type="warn">
这是一个服务端渲染的警告。无需 JS。
</Callout>
在 MDX 中导入的组件会在构建/SSR 时运行,除非它们是岛屿。
混合 SSR
// astro.config.mjs
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'hybrid',
adapter: cloudflare(),
});
---
// src/pages/api/search.ts — 在边缘运行
export const prerender = false;
export async function GET({ request }) {
const url = new URL(request.url);
const q = url.searchParams.get('q') ?? '';
const results = await search(q);
return new Response(JSON.stringify(results), { headers: { 'content-type': 'application/json' } });
}
prerender = false 将该路由设为 SSR;站点的其余部分保持静态。
反模式
到处都用 client:load
症状: Lighthouse JS 包体积膨胀;Astro 的水合优势消失。
诊断: 工程师默认使用 client:load,因为它最熟悉。
修复: 默认使用 client:idle 或 client:visible。仅在首屏交互时使用 client:load。
在客户端组件中获取数据
症状: 每个页面都出现加载动画;SEO 受损。
诊断: 数据获取被移到 React 组件中,而不是在 Astro 前端代码中完成。
修复: 在 --- 定界符内获取数据,在服务端渲染,然后将数据作为 props 传递给岛屿组件。
前端数据无类型
症状: 构建成功;生产环境标题显示 undefined。
诊断: 没有内容集合 schema;前端数据拼写错误未被发现。
修复: 使用带有 zod schema 的 defineCollection。前端数据错误会在构建时失败。
混合使用 public/ 和 src/assets/ 存放图像
症状: 部分图像被优化,其他图像保持原始大小。
诊断: public/ 直接原样提供;只有 src/assets/ 会经过 Sharp 处理。
修复: 将图像移动到 src/assets/。始终使用 <Image> 组件。public/ 仅用于 OG 图像和 favicon。
尝试使用 Astro 构建 SPA
症状: 不断与水合机制作斗争;岛屿不断膨胀直到整个页面都是交互的。 诊断: 框架选择错误。Astro 擅长内容;SPA 需要使用 Next/Remix。 修复: 当大多数页面都需要交互时,使用 Next/Remix。对于营销 + 文档,使用 Astro。
过度使用 client:only
症状: 每次页面加载都出现布局偏移 (CLS);内容出现前有“闪烁”。
诊断: 跳过 SSR 意味着浏览器在 JS 运行前看到一个空占位符。
修复: 仅当组件确实无法在服务端渲染时才使用 client:only。提供一个能近似最终大小的占位符。
质量门禁
- 默认客户端指令是
client:idle或client:visible;client:load的使用需经理由说明。 - 所有内容都通过
defineCollection拥有类型化的 schema。 - 图像位于
src/assets/下并使用<Image>组件。 - 仅当组件存在时才添加多框架集成(
@astrojs/react等)。 - 在速度最慢的代表性页面上,LCP 低于 2 秒。
- 为每个页面设置首次加载 JS 预算;CI 在出现回归时失败。
- MDX 使用 Astro 组件处理静态部分;仅在需要交互的地方使用岛屿。
- 在主要导航路径上测试了视图过渡。
不适用场景
- 完整 SPA — Next.js、Remix、TanStack Start 更合适。
- Astro 插件/集成开发 — 单独技能(目前没有专门技能)。
- Vite 构建调优 — Astro 底层使用 Vite。请参阅
vite-build-optimizer处理代码分割、HMR、插件生命周期问题。 - 重客户端状态应用(仪表盘、实时工具)— 需要过多 JS,岛屿难以发挥作用。
- 原生移动端 — Astro 仅限 Web。