Astro Islands 架构深入：选择性注水的革命性方案

前言#

传统的 SPA 框架有一个根本性的问题：即使页面上 90% 的内容是静态的，也要为 100% 的内容加载和执行 JavaScript。这意味着一篇博客文章的「点赞按钮」需要和整个页面的渲染框架一起下载、解析、执行。

Astro 的 Islands 架构（岛屿架构）彻底翻转了这个范式——默认零 JavaScript，只为需要交互的组件注入最少量的 JS。这不是渐进增强的老调重弹，而是一套基于「选择性注水（Partial Hydration）」的现代化解决方案。

本文将深入 Islands 架构的原理、Astro 的 client:* 指令体系、多框架集成机制，以及它带来的真实性能优势。

一、Islands 架构的核心思想#

1.1 从 SPA 到 MPA 再到 Islands#

1
传统 MPA（Multi-Page Application）:
2
┌─────────────────────────────┐
3
│       服务端渲染 HTML        │  ← 每个页面都是完整 HTML
4
│   (零或极少 JavaScript)      │  ← 交互能力有限
5
└─────────────────────────────┘
6

7
SPA（Single-Page Application）:
8
┌─────────────────────────────┐
9
│     JavaScript 接管一切       │  ← 客户端渲染
10
│   (加载大量 JS bundle)       │  ← 首屏慢，FCP/LCP 差
11
└─────────────────────────────┘
12

13
SSR + Hydration（Next.js/Nuxt 模式）:
14
┌─────────────────────────────┐
15
│  服务端渲染 HTML + 全页注水   │  ← 首屏快，但 TTI 慢
16
│  (仍然加载全量 JS)           │  ← 注水过程阻塞交互
17
└─────────────────────────────┘
18

19
Islands Architecture（Astro 模式）:
20
┌─────────────────────────────┐
21
│ ┌──────┐  静态   ┌────────┐ │
22
│ │Island│  HTML   │ Island │ │  ← 静态部分零 JS
23
│ │ (Vue)│         │(Svelte)│ │  ← 每个岛屿独立注水
24
│ └──────┘         └────────┘ │  ← 可以混合多框架
25
│      静态 HTML 内容          │
26
│ ┌────────────────────┐      │
27
│ │   Island (Vanilla)  │      │
28
│ └────────────────────┘      │
29
└─────────────────────────────┘

1.2 什么是「岛屿」#

在 Islands 架构中，页面被分为两种区域：

静态海洋（Static Sea）：纯 HTML/CSS，不需要任何 JavaScript。这是页面的主体——导航栏、文章内容、页脚等。
交互岛屿（Interactive Islands）：需要 JavaScript 来实现交互的组件。如搜索框、评论区、轮播图、点赞按钮等。

关键原则：每个岛屿独立加载、独立注水、互不影响。

1.3 选择性注水 vs 全页注水#

1
// 传统全页注水（Next.js / Nuxt 模式）
2
// 整个页面的组件树都需要在客户端重新激活
3

4
// 服务端输出：
5
// <html>
6
//   <body>
7
//     <header>...</header>          ← 需要 JS 注水
8
//     <nav>...</nav>               ← 需要 JS 注水
9
//     <main>
10
//       <article>5000字文章</article> ← 需要 JS 注水（虽然是纯静态的！）
11
//       <LikeButton />              ← 需要 JS 注水
12
//     </main>
13
//     <footer>...</footer>          ← 需要 JS 注水
14
//   </body>
15
// </html>
16

17
// 客户端需要下载整个应用的 JS bundle，然后：
18
// hydrate(<App />, document.getElementById('root'))
19
// ↑ 遍历整个组件树，绑定事件、恢复状态
20

21

22
// Astro 选择性注水：
23
// 只有 LikeButton 需要注水，其他都是纯 HTML
24

25
// 服务端输出：
26
// <html>
27
//   <body>
28
//     <header>...</header>          ← 纯 HTML，零 JS
29
//     <nav>...</nav>               ← 纯 HTML，零 JS
30
//     <main>
31
//       <article>5000字文章</article> ← 纯 HTML，零 JS
32
//       <astro-island>              ← 独立注水
33
//         <LikeButton />
34
//       </astro-island>
35
//     </main>
36
//     <footer>...</footer>          ← 纯 HTML，零 JS
37
//   </body>
38
// </html>

二、Astro 的组件模型#

2.1 .astro 组件#

Astro 组件（.astro 文件）是服务端组件，它们在构建时执行，输出纯 HTML：

1
---
2
// 这里是服务端代码（frontmatter），在构建时执行
3
interface Props {
4
  title: string;
5
  excerpt: string;
6
  date: string;
7
  slug: string;
8
  tags: string[];
9
}
10

11
const { title, excerpt, date, slug, tags } = Astro.props;
12

13
// 可以调用数据库、API 等（构建时执行）
14
const formattedDate = new Date(date).toLocaleDateString('zh-CN', {
15
  year: 'numeric',
16
  month: 'long',
17
  day: 'numeric',
18
});
19
---
20

21
<!-- 这里是模板，编译为纯 HTML -->
22
<article class="card">
23
  <a href={`/posts/${slug}`}>
24
    <h2>{title}</h2>
25
    <time datetime={date}>{formattedDate}</time>
26
    <p>{excerpt}</p>
27
    <div class="tags">
28
      {tags.map(tag => (
29
        <span class="tag">{tag}</span>
30
      ))}
31
    </div>
32
  </a>
33
</article>
34

35
<style>
36
  /* Scoped CSS - 自动添加唯一作用域 */
37
  .card {
38
    border: 1px solid #e2e8f0;
39
    border-radius: 0.5rem;
40
    padding: 1.5rem;
41
    transition: box-shadow 0.2s;
42
  }
43
  .card:hover {
44
    box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
45
  }
46
  .tag {
47
    display: inline-block;
48
    padding: 0.25rem 0.5rem;
49
    background: #edf2f7;
50
    border-radius: 0.25rem;
51
    font-size: 0.875rem;
52
  }
53
</style>

关键点：.astro 组件永远不会发送 JavaScript 到客户端。 它们是纯粹的模板引擎。

2.2 框架组件作为岛屿#

当你需要交互时，可以使用任何前端框架的组件，并通过 client:* 指令将其标记为岛屿：

1
---
2
import Layout from '@/layouts/Layout.astro';
3
import ArticleContent from '@/components/ArticleContent.astro';
4
// 框架组件
5
import LikeButton from '@/components/LikeButton.vue';
6
import CommentSection from '@/components/CommentSection.svelte';
7
import ShareMenu from '@/components/ShareMenu.vue';
8
import TableOfContents from '@/components/TableOfContents.vue';
9

10
const { slug } = Astro.params;
11
const post = await getPost(slug);
12
---
13

14
<Layout title={post.title}>
15
  <article>
16
    <!-- 静态内容：零 JS -->
17
    <h1>{post.title}</h1>
18
    <time>{post.date}</time>
19
    <ArticleContent content={post.content} />
20

21
    <!-- 交互岛屿：各自独立加载 JS -->
22
    <LikeButton client:visible postId={post.id} />
23
    <ShareMenu client:idle url={Astro.url.href} title={post.title} />
24
    <TableOfContents client:media="(min-width: 1024px)" headings={post.headings} />
25
    <CommentSection client:visible postId={post.id} />
26
  </article>
27
</Layout>

三、client:* 指令深入#

3.1 所有指令及其行为#

Astro 提供了 5 种 client:* 指令，控制岛屿何时被注水：

1
<!-- 1. client:load - 页面加载后立即注水 -->
2
<!-- 适用于：首屏可见且需要立即交互的组件 -->
3
<SearchBar client:load />
4

5
<!-- 2. client:idle - 浏览器空闲时注水（requestIdleCallback） -->
6
<!-- 适用于：不紧急但最终需要的组件 -->
7
<ShareMenu client:idle />
8

9
<!-- 3. client:visible - 组件进入视口时注水（IntersectionObserver） -->
10
<!-- 适用于：折叠下方的组件，用户滚动到才加载 -->
11
<CommentSection client:visible />
12

13
<!-- 4. client:media - 满足媒体查询条件时注水 -->
14
<!-- 适用于：响应式场景，如只在桌面端加载的侧边栏 -->
15
<DesktopSidebar client:media="(min-width: 1024px)" />
16

17
<!-- 5. client:only - 跳过 SSR，只在客户端渲染 -->
18
<!-- 适用于：依赖浏览器 API 的组件（如 canvas、WebGL） -->
19
<ThreeJSScene client:only="vue" />

3.2 指令的内部实现原理#

Astro 的 client:* 指令在编译时被转换为特定的加载脚本。以下是其内部机制的简化版本：

1
// Astro 内部：岛屿注水的运行时代码（简化）
2

3
// astro-island 自定义元素
4
class AstroIsland extends HTMLElement {
5
  connectedCallback() {
6
    // 读取指令类型
7
    const directive = this.getAttribute('client');
8
    // 读取组件信息
9
    const componentUrl = this.getAttribute('component-url');
10
    const componentExport = this.getAttribute('component-export') || 'default';
11
    const rendererUrl = this.getAttribute('renderer-url');
12
    const props = JSON.parse(this.getAttribute('props') || '{}');
13

14
    // 根据指令类型决定注水时机
15
    switch (directive) {
16
      case 'load':
17
        this.hydrate(componentUrl, rendererUrl, componentExport, props);
18
        break;
19

20
      case 'idle':
21
        this.hydrateOnIdle(componentUrl, rendererUrl, componentExport, props);
22
        break;
23

24
      case 'visible':
25
        this.hydrateOnVisible(componentUrl, rendererUrl, componentExport, props);
26
        break;
27

28
      case 'media':
29
        this.hydrateOnMedia(
30
          this.getAttribute('client-value'),
31
          componentUrl, rendererUrl, componentExport, props
32
        );
33
        break;
34
    }
35
  }
36

37
  async hydrate(componentUrl, rendererUrl, exportName, props) {
38
    // 1. 动态加载组件代码和框架渲染器
39
    const [componentModule, renderer] = await Promise.all([
40
      import(/* @vite-ignore */ componentUrl),
41
      import(/* @vite-ignore */ rendererUrl),
42
    ]);
43

44
    const Component = componentModule[exportName];
45

46
    // 2. 使用对应框架的渲染器进行注水
47
    // renderer 是框架特定的（如 @astrojs/vue 提供的渲染器）
48
    await renderer.default(this, Component, props, this.innerHTML);
49
  }
50

51
  hydrateOnIdle(componentUrl, rendererUrl, exportName, props) {
52
    // 使用 requestIdleCallback 延迟注水
53
    const cb = () => this.hydrate(componentUrl, rendererUrl, exportName, props);
54

55
    if ('requestIdleCallback' in window) {
56
      requestIdleCallback(cb);
57
    } else {
58
      // fallback: 200ms 后执行
59
      setTimeout(cb, 200);
60
    }
61
  }
62

63
  hydrateOnVisible(componentUrl, rendererUrl, exportName, props) {
64
    // 使用 IntersectionObserver 在组件可见时注水
65
    const observer = new IntersectionObserver(
66
      (entries) => {
67
        for (const entry of entries) {
68
          if (entry.isIntersecting) {
69
            observer.disconnect();
70
            this.hydrate(componentUrl, rendererUrl, exportName, props);
71
            break;
72
          }
73
        }
74
      },
75
      { rootMargin: '200px' } // 提前 200px 开始加载
76
    );
77
    observer.observe(this);
78
  }
79

80
  hydrateOnMedia(query, componentUrl, rendererUrl, exportName, props) {
81
    // 使用 matchMedia 在媒体查询匹配时注水
82
    const mql = matchMedia(query);
83

84
    if (mql.matches) {
85
      this.hydrate(componentUrl, rendererUrl, exportName, props);
86
    } else {
87
      const handler = (e) => {
88
        if (e.matches) {
89
          mql.removeEventListener('change', handler);
90
          this.hydrate(componentUrl, rendererUrl, exportName, props);
91
        }
92
      };
93
      mql.addEventListener('change', handler);
94
    }
95
  }
96
}
97

98
customElements.define('astro-island', AstroIsland);

3.3 编译产物分析#

当 Astro 编译一个包含岛屿的页面时，产物结构如下：

1
<!-- 构建后的 HTML（简化） -->
2
<astro-island
3
  uid="abc123"
4
  component-url="/_astro/LikeButton.vue_vue_type_script_setup_true_lang.BxK2n.js"
5
  component-export="default"
6
  renderer-url="/_astro/client.Cm9k1.js"
7
  props='{"postId":[0,42]}'
8
  client="visible"
9
>
10
  <!-- 服务端预渲染的 HTML（用户立即可见） -->
11
  <button class="like-btn">
12
    <svg>...</svg>
13
    <span>42</span>
14
  </button>
15
</astro-island>

注意几个关键点：

组件代码按需加载：只有当注水条件满足时，才会下载组件 JS
服务端预渲染：岛屿内部有完整的 HTML，用户无需等待 JS 就能看到内容
Props 序列化：组件 props 被序列化为 JSON，注水时传入

3.4 选择合适的指令#

1
// 决策指南
2

3
// ✅ client:load - 首屏关键交互
4
// 场景：搜索框、导航菜单、需要立即可用的表单
5
// 代价：阻塞页面加载，慎用
6

7
// ✅ client:idle - 次优先级交互
8
// 场景：分享按钮、主题切换、非紧急工具栏
9
// 原理：requestIdleCallback，在浏览器空闲时执行
10
// 通常在页面加载后 50-200ms 内触发
11

12
// ✅ client:visible - 折叠下方内容（最常用）
13
// 场景：评论区、相关文章、无限滚动、图表
14
// 原理：IntersectionObserver，滚动到附近才加载
15
// 设置了 200px 的 rootMargin，提前预加载
16

17
// ✅ client:media - 响应式条件
18
// 场景：桌面端侧边栏、移动端底部导航
19
// 原理：matchMedia，只在条件满足时注水
20

21
// ✅ client:only - 纯客户端组件
22
// 场景：Canvas/WebGL、使用 window/document 的组件
23
// 注意：不会 SSR，SEO 不友好，仅在必要时使用

四、多框架集成#

4.1 安装多框架支持#

Astro 的一大杀手级特性是同一个项目中可以使用多个框架：

1
# 安装集成
2
npx astro add vue
3
npx astro add svelte
4
npx astro add solid-js
5
npx astro add lit

1
import { defineConfig } from 'astro/config';
2
import vue from '@astrojs/vue';
3
import svelte from '@astrojs/svelte';
4
import solidJs from '@astrojs/solid-js';
5
import lit from '@astrojs/lit';
6

7
export default defineConfig({
8
  integrations: [
9
    vue(),
10
    svelte(),
11
    solidJs(),
12
    lit(),
13
  ],
14
});

4.2 混合使用不同框架#

1
---
2
// 根据组件特点选择最合适的框架
3

4
// Vue - 复杂的表单和状态管理
5
import DataForm from '@/components/vue/DataForm.vue';
6

7
// Svelte - 轻量级动画组件
8
import AnimatedChart from '@/components/svelte/AnimatedChart.svelte';
9

10
// Solid - 高频更新的实时数据
11
import LiveTicker from '@/components/solid/LiveTicker.tsx';
12

13
// Lit - Web Component，可复用于任何框架
14
import CustomTooltip from '@/components/lit/CustomTooltip.ts';
15

16
const dashboardData = await fetchDashboardData();
17
---
18

19
<Layout>
20
  <h1>Dashboard</h1>
21

22
  <!-- 每个组件使用最适合它的框架 -->
23
  <section class="form-section">
24
    <DataForm client:load initialData={dashboardData.form} />
25
  </section>
26

27
  <section class="charts">
28
    <AnimatedChart client:visible data={dashboardData.chart} />
29
  </section>
30

31
  <section class="live-data">
32
    <LiveTicker client:load endpoint="/api/ticker" />
33
  </section>
34

35
  <!-- Lit Web Component 可以在任何地方使用 -->
36
  <CustomTooltip client:idle text="这是一个提示">
37
    <button>Hover me</button>
38
  </CustomTooltip>
39
</Layout>

4.3 框架渲染器的工作原理#

每个框架集成都提供了一个「渲染器」，负责服务端渲染和客户端注水：

1
// @astrojs/vue 的渲染器（简化）
2
// server.js - 服务端渲染
3
import { createSSRApp, h } from 'vue';
4
import { renderToString } from 'vue/server-renderer';
5

6
export async function renderToStaticMarkup(Component, props, slotted) {
7
  const app = createSSRApp({
8
    render() {
9
      return h(Component, props, {
10
        default: () => slotted?.default ? h('astro-slot', { innerHTML: slotted.default }) : undefined,
11
      });
12
    },
13
  });
14

15
  const html = await renderToString(app);
16
  return { html };
17
}
18

19
// client.js - 客户端注水
20
import { createSSRApp, h } from 'vue';
21

22
export default async function clientEntrypoint(
23
  element,      // astro-island DOM 元素
24
  Component,    // Vue 组件
25
  props,        // 序列化的 props
26
  slotHTML      // 插槽内容的 HTML
27
) {
28
  // 创建 Vue 应用并注水到已有的 DOM 上
29
  const app = createSSRApp({
30
    render() {
31
      return h(Component, props, {
32
        default: slotHTML
33
          ? () => h('astro-slot', { innerHTML: slotHTML })
34
          : undefined,
35
      });
36
    },
37
  });
38

39
  // 注水（hydrate）而不是全新渲染（mount）
40
  app.mount(element, true); // true = hydrate mode
41
}

4.4 跨框架通信#

岛屿之间默认是隔离的，但可以通过多种方式通信：

1
// 方案一：Nano Stores（Astro 推荐的跨框架状态共享方案）
2
// npm install nanostores @nanostores/vue @nanostores/solid
3

4
// stores/cart.ts - 框架无关的 Store
5
import { atom, computed } from 'nanostores';
6

7
export interface CartItem {
8
  id: string;
9
  name: string;
10
  price: number;
11
  quantity: number;
12
}
13

14
export const $cartItems = atom<CartItem[]>([]);
15

16
export const $cartTotal = computed($cartItems, (items) =>
17
  items.reduce((sum, item) => sum + item.price * item.quantity, 0)
18
);
19

20
export function addToCart(item: Omit<CartItem, 'quantity'>) {
21
  const items = $cartItems.get();
22
  const existing = items.find(i => i.id === item.id);
23
  if (existing) {
24
    $cartItems.set(
25
      items.map(i => i.id === item.id ? { ...i, quantity: i.quantity + 1 } : i)
26
    );
27
  } else {
28
    $cartItems.set([...items, { ...item, quantity: 1 }]);
29
  }
30
}
31

32
export function removeFromCart(id: string) {
33
  $cartItems.set($cartItems.get().filter(i => i.id !== id));
34
}

1
<!-- Vue 组件中使用 -->
2
<script setup>
3
import { useStore } from '@nanostores/vue';
4
import { $cartItems, $cartTotal, addToCart } from '@/stores/cart';
5

6
const cartItems = useStore($cartItems);
7
const total = useStore($cartTotal);
8
</script>
9

10
<template>
11
  <div class="cart">
12
    <div v-for="item in cartItems" :key="item.id">
13
      {{ item.name }} x{{ item.quantity }} - ¥{{ item.price * item.quantity }}
14
    </div>
15
    <p>总计: ¥{{ total }}</p>
16
  </div>
17
</template>

1
// Solid 组件中使用同一个 Store
2
import { useStore } from '@nanostores/solid';
3
import { $cartTotal, addToCart } from '@/stores/cart';
4

5
function AddToCartButton(props: { product: { id: string; name: string; price: number } }) {
6
  const total = useStore($cartTotal);
7

8
  return (
9
    <button onClick={() => addToCart(props.product)}>
10
      加入购物车 (当前总计: ¥{total()})
11
    </button>
12
  );
13
}

1
// 方案二：Custom Events（轻量级通信）
2
// 适合简单的事件通知场景
3

4
// 发送事件（任意框架组件内）
5
function notifyCartUpdate(item: CartItem) {
6
  const event = new CustomEvent('cart:update', {
7
    detail: item,
8
    bubbles: true,
9
  });
10
  document.dispatchEvent(event);
11
}
12

13
// 监听事件（任意框架组件内）
14
// Vue
15
import { onMounted, onUnmounted } from 'vue';
16

17
onMounted(() => {
18
  const handler = (e: CustomEvent) => {
19
    console.log('Cart updated:', e.detail);
20
  };
21
  document.addEventListener('cart:update', handler);
22
  onUnmounted(() => document.removeEventListener('cart:update', handler));
23
});

五、性能优势量化分析#

5.1 真实场景对比#

以一个典型的技术博客页面为例：

1
页面组成:
2
- 导航栏（静态）
3
- 文章标题和元信息（静态）
4
- 文章正文 5000 字（静态）
5
- 代码高亮块 x 10（静态，构建时高亮）
6
- 目录导航（交互：滚动高亮）
7
- 点赞按钮（交互：API 调用）
8
- 评论区（交互：表单+列表）
9
- 相关文章推荐（静态）
10
- 页脚（静态）

1
传统 SSR (Nuxt/Next) 的 JS 产物:
2
├── framework-runtime.js    ~45KB (gzip)   ← 框架运行时
3
├── app.js                  ~30KB (gzip)   ← 应用代码
4
├── vendor.js               ~25KB (gzip)   ← 第三方依赖
5
├── page-blog-slug.js       ~15KB (gzip)   ← 页面组件
6
└── Total:                  ~115KB (gzip)  ← 全页注水
7

8
Astro Islands 的 JS 产物:
9
├── toc-widget.js            ~3KB (gzip)   ← 目录组件
10
├── like-button.js           ~2KB (gzip)   ← 点赞组件
11
├── comment-section.js       ~8KB (gzip)   ← 评论组件
12
├── vue-runtime (shared)    ~15KB (gzip)   ← 框架运行时（仅注水组件需要）
13
└── Total:                  ~28KB (gzip)   ← 只加载需要的
14

15
JS 减少: 75%+

5.2 Core Web Vitals 影响#

1
指标对比（典型博客页面）:
2

3
                    传统 SSR     Astro Islands    提升
4
FCP (First         0.8s         0.6s             25%
5
Contentful Paint)
6

7
LCP (Largest       1.2s         0.8s             33%
8
Contentful Paint)
9

10
TBT (Total         350ms        50ms             86%
11
Blocking Time)
12

13
TTI (Time to       2.5s         0.9s             64%
14
Interactive)
15

16
CLS (Cumulative    0.05         0.02             60%
17
Layout Shift)

TBT 的巨大差异是关键：传统 SSR 需要解析和执行大量 JS 来完成注水，这期间主线程被阻塞。Astro 只需注水少量岛屿组件，主线程几乎不被阻塞。

5.3 性能优化技巧#

1
---
2
// 技巧 1: 预加载关键岛屿的 JS
3
// 在 <head> 中预加载即将需要的组件
4
---
5
<head>
6
  <!-- 预加载 client:load 组件的 JS -->
7
  <link rel="modulepreload" href="/_astro/SearchBar.BxK2n.js" />
8
</head>
9

10
<!-- 技巧 2: 使用 transition:persist 保持岛屿状态 -->
11
<!-- 在 View Transitions 中，岛屿状态不会丢失 -->
12
<nav transition:persist>
13
  <ThemeToggle client:load transition:persist />
14
</nav>
15

16
<!-- 技巧 3: 服务端数据预取，避免客户端瀑布 -->
17
---
18
// 在服务端获取数据，作为 props 传入
19
const comments = await fetchComments(post.id);
20
---
21
<CommentSection client:visible initialComments={comments} postId={post.id} />
22
<!-- 评论区注水后已有数据，无需额外请求 -->

1
---
2
// 技巧 4: 合理拆分岛屿粒度
3

4
// ❌ 不好：整个侧边栏作为一个大岛屿
5
// <Sidebar client:load /> ← 加载了很多不需要交互的内容的 JS
6

7
// ✅ 好：只把需要交互的部分作为岛屿
8
---
9
<aside>
10
  <!-- 静态内容 -->
11
  <h3>作者信息</h3>
12
  <p>张三，前端工程师</p>
13

14
  <!-- 只有搜索框需要 JS -->
15
  <SearchWidget client:idle />
16

17
  <!-- 静态分类列表 -->
18
  <h3>分类</h3>
19
  <ul>
20
    {categories.map(cat => <li><a href={cat.url}>{cat.name}</a></li>)}
21
  </ul>
22

23
  <!-- 只有订阅表单需要 JS -->
24
  <NewsletterForm client:visible />
25
</aside>

六、实战：构建一个完整的博客#

6.1 项目结构#

1
my-blog/
2
├── astro.config.mjs
3
├── src/
4
│   ├── components/
5
│   │   ├── astro/           # 静态 Astro 组件
6
│   │   │   ├── Header.astro
7
│   │   │   ├── Footer.astro
8
│   │   │   ├── PostCard.astro
9
│   │   │   └── Prose.astro
10
│   │   ├── vue/             # Vue 交互组件
11
│   │   │   ├── SearchBar.vue
12
│   │   │   ├── ThemeToggle.vue
13
│   │   │   └── CommentForm.vue
14
│   │   └── svelte/          # Svelte 轻量组件
15
│   │       ├── LikeButton.svelte
16
│   │       └── ReadingProgress.svelte
17
│   ├── content/
18
│   │   └── posts/           # Markdown 文章
19
│   ├── layouts/
20
│   │   └── PostLayout.astro
21
│   ├── pages/
22
│   │   ├── index.astro
23
│   │   └── posts/
24
│   │       └── [...slug].astro
25
│   └── stores/
26
│       └── theme.ts         # Nano Stores
27
├── public/
28
└── package.json

6.2 文章页面实现#

1
---
2
import { getCollection, type CollectionEntry } from 'astro:content';
3
import PostLayout from '@/layouts/PostLayout.astro';
4
import Prose from '@/components/astro/Prose.astro';
5

6
// 交互岛屿
7
import ReadingProgress from '@/components/svelte/ReadingProgress.svelte';
8
import LikeButton from '@/components/svelte/LikeButton.svelte';
9
import SearchBar from '@/components/vue/SearchBar.vue';
10
import CommentForm from '@/components/vue/CommentForm.vue';
11

12
export async function getStaticPaths() {
13
  const posts = await getCollection('posts');
14
  return posts.map((post) => ({
15
    params: { slug: post.slug },
16
    props: { post },
17
  }));
18
}
19

20
type Props = { post: CollectionEntry<'posts'> };
21
const { post } = Astro.props;
22
const { Content, headings } = await post.render();
23

24
// 服务端获取点赞数和评论
25
const [likeCount, comments] = await Promise.all([
26
  fetch(`${import.meta.env.API_URL}/likes/${post.slug}`).then(r => r.json()),
27
  fetch(`${import.meta.env.API_URL}/comments/${post.slug}`).then(r => r.json()),
28
]);
29
---
30

31
<PostLayout title={post.data.title}>
32
  <!-- 阅读进度条 - 页面加载即需要 -->
33
  <ReadingProgress client:load />
34

35
  <!-- 搜索 - 空闲时加载 -->
36
  <SearchBar client:idle slot="header-actions" />
37

38
  <article>
39
    <header>
40
      <h1>{post.data.title}</h1>
41
      <time datetime={post.data.published.toISOString()}>
42
        {post.data.published.toLocaleDateString('zh-CN')}
43
      </time>
44
      <div class="tags">
45
        {post.data.tags.map(tag => (
46
          <a href={`/tags/${tag}`} class="tag">{tag}</a>
47
        ))}
48
      </div>
49
    </header>
50

51
    <!-- 文章内容 - 纯静态 HTML，零 JS -->
52
    <Prose>
53
      <Content />
54
    </Prose>
55

56
    <!-- 点赞 - 滚动到可见时加载 -->
57
    <LikeButton
58
      client:visible
59
      slug={post.slug}
60
      initialCount={likeCount.count}
61
    />
62

63
    <!-- 评论 - 滚动到可见时加载 -->
64
    <CommentForm
65
      client:visible
66
      slug={post.slug}
67
      initialComments={comments}
68
    />
69
  </article>
70
</PostLayout>

6.3 View Transitions 集成#

1
---
2
import { ViewTransitions } from 'astro:transitions';
3
import Header from '@/components/astro/Header.astro';
4
import ThemeToggle from '@/components/vue/ThemeToggle.vue';
5
---
6

7
<html lang="zh-CN">
8
<head>
9
  <meta charset="utf-8" />
10
  <meta name="viewport" content="width=device-width, initial-scale=1" />
11
  <title>{Astro.props.title}</title>
12
  <!-- View Transitions API -->
13
  <ViewTransitions />
14
</head>
15
<body>
16
  <Header>
17
    <!-- 主题切换在页面导航时保持状态 -->
18
    <ThemeToggle client:load transition:persist />
19
  </Header>
20

21
  <main transition:animate="slide">
22
    <slot />
23
  </main>
24
</body>
25
</html>

七、Islands 架构的局限性#

7.1 不适合的场景#

1
❌ 高度交互的 SPA 应用（如 Figma、Google Docs）
2
   → 整个页面都是交互式的，Islands 没有优势
3

4
❌ 需要复杂客户端路由的应用
5
   → Islands 是 MPA 模式，页面导航是全页刷新（虽然 View Transitions 缓解了这个问题）
6

7
❌ 岛屿之间需要大量频繁通信
8
   → 跨岛屿状态同步有额外复杂度
9

10
❌ 需要离线支持的 PWA
11
   → MPA 模式下 Service Worker 配置更复杂

7.2 何时选择 Islands#

1
✅ 内容驱动的网站（博客、文档、营销页面）
2
✅ 电商产品页面（大量静态描述 + 少量交互）
3
✅ 新闻/媒体网站（内容为主）
4
✅ 企业官网/落地页
5
✅ 对 Core Web Vitals 有严格要求的项目
6
✅ 需要极致首屏性能的场景

总结#

Islands 架构代表了前端性能优化的一次范式转移：

默认零 JS：页面主体是纯 HTML，性能天花板极高
选择性注水：5 种 client:* 指令精确控制何时加载 JS
框架无关：同一页面可以混用 Vue、Svelte、Solid 等
渐进增强：即使 JS 加载失败，用户仍能看到完整内容
极致性能：典型场景下 JS 减少 75%+，TBT 降低 80%+

Astro 不是要取代 Vue 或 Svelte——它是让你在正确的地方使用正确的工具。如果你的项目是内容驱动的，Islands 架构几乎是 2026 年的最优选择。

“The best JavaScript is no JavaScript. The second best is the least JavaScript.” —— Islands 架构的哲学

音乐

音乐

前言#