企业官网建设流程全解析

Astro 的岛屿架构是我近几年接触前端新方案后，第一个觉得“可以把性能问题从根源上重新定义”的思路。以前做页面优化，大家拼的是压缩体积、拆包、上CDN、缓存策略，说白了都是在已有产物里抠空间；但岛屿架构直接改变了问题的提问方式——哪些页面内容必须加载脚本，哪些可以完全不碰JavaScript。这篇文章我会从架构演进、Astro 的落地机制、具体实操到踩坑记录，完整拆一遍这套方案，帮你在自己的项目里判断它到底合不合适。

1. 岛屿架构到底解决了什么问题——先把它脱胎于何处讲清楚

1.1 从MPA到SPA的极端摆动，再到“缺什么补什么”

如果你是从jQuery时代写过来的前端，应该对MPA（多页面应用）不陌生。那时候每个页面都是独立的HTML，点击跳转就刷新页面，服务器直接把整张页面吐回来，交互逻辑靠零散的script标签撑着。这种方式最大的好处是首屏成本低——浏览器拿到什么就渲染什么；最大的坏处是页面切换有白屏等待，交互组件一多，脚本管理就成了一团乱麻。

后来SPA（单页面应用）把这个问题解决了，但解决方式有点用力过猛。React、Vue这类框架把整个应用塞进一个<div id="root">里，前端拿到一个几乎空白的HTML外壳，再通过JavaScript把整棵组件树渲染出来。这种方式在后台管理系统、重交互应用里非常好用，因为它让页面切换变成了纯前端动作，不再依赖服务器往返。但代价同样明显：哪怕你的页面只有一个按钮需要交互，浏览器也得下载、解析、执行整套框架运行时。一个内容站首页可能只有一篇长文和一个评论区，却要为一个评论框付出几百KB的成本。

后来SSR（服务端渲染）和静态站点生成出现了，Next.js、Nuxt这类框架在服务端把React/Vue组件渲染成HTML字符串，再在浏览器端做水合（hydration），让页面既有SEO又有交互。但这里有个隐藏问题：这种方案是“全量水合”。服务端确实把整张HTML吐出来了，可浏览器端脚本一启动，还是会挨个激活页面上所有组件，哪怕有些组件根本不需要任何交互逻辑。一个详情页99%的内容都是静态文本，浏览器依然要为整个页面绑定事件、初始化状态、构建虚拟DOM树。性能能比纯客户端渲染好，但离“零浪费”还有不小距离。

1.2 岛屿架构：大片静态海洋中的交互小岛

岛屿架构（Islands Architecture）的核心比喻特别直观：把整张页面想象成一片海洋，海洋里的绝大多数区域都是静态的、不需要JavaScript参与的HTML；只有少数交互组件像是分布在海面上的岛屿，浏览器只需要针对这些“岛屿”加载脚本、执行水合，其他部分全部保持静态。

这个概念最初由Etsy的前端架构师Katie Sylor-Miller提出，后来在Astro、Eleventy等框架中被大规模落地。Astro把它作为默认设计原则：每个.astro组件编译后默认输出纯HTML和CSS，JavaScript字节数为零。只有你在模板里显式给组件加上client:*指令，Astro才会把该组件及其依赖打包成独立的JavaScript chunk，在指定时机加载并水合。

这意味着两点。第一，打包产物是页面维度的，不是应用维度的。每个交互组件对应一个或几个独立脚本，页面引入了三个交互组件，浏览器就最多加载三个脚本，而不是一个包含整个应用逻辑的大包。第二，静态内容完全游离在框架运行时之外。React/Vue/Svelte的runtime只在被激活的岛屿内部起作用，不会“感染”周围的大片静态HTML。

1.3 岛屿架构与SSR全量水合的根本差异

把岛屿架构和传统SSR放在一起对比，差异非常清晰。传统SSR的工作流是：服务端渲染出HTML → 浏览器显示页面 → 下载整个应用脚本 →在页面根节点上执行全量水合。水合的过程等于重新跑一遍React/Vue在客户端的所有逻辑，把虚拟DOM和真实DOM做匹配，绑定事件代理，初始化状态。页面里的静态部分是顺带被“水合”的，它们本身没这个需求，但用户必须为它们买单。

岛屿架构则是：服务端/构建期渲染出HTML → 浏览器显示页面 →只下载并水合被标记的交互岛屿→ 静态区域保持纯HTML。成本从“整个应用”变成“每个岛屿各自承担”。更妙的是，这种水合的粒度是组件级的，岛屿之间互相独立，没有全局事件总线或共享运行时依赖，你可以混用React、Vue、Svelte写的不同岛屿组件，只要它们各自编译出的脚本互不依赖就行。

我用一个数字来直观说明：我之前把一个React的SSR信息流页面迁移到Astro，页面上只有一个搜索框和导航栏是交互组件，其余全是文章列表内容。迁移前HTML约80KB、JavaScript约245KB；迁移后HTML变成了120KB左右（更多静态内容被直接输出），JavaScript降到了12KB，只剩一个搜索框的逻辑。首屏渲染时间在低端Android设备上大约快了一倍，因为浏览器省去了下载、解析、执行200多KB脚本的大量时间。

2. Astro如何把岛屿架构落成代码——核心机制逐个拆

2.1 默认零JavaScript的编译模型

Astro最反直觉的地方在于：虽然你可以在项目里写React、Vue、Svelte组件，但Astro本身是一个编译时框架，不是运行时框架。它没有像Next.js那样在浏览器端跑一个“Astro运行时”来调度一切。Astro构建器会在编译阶段读取所有.astro文件，把它们转换成静态HTML字符串，再把页面引用的框架组件编译成独立脚本模块。

这个设计带来了一个很多人容易忽略的事实：Astro项目最终产出的静态站点，几乎没有“框架壳”。你部署到服务器上的文件是纯HTML、CSS、JS，不包含任何运行时引导逻辑。这一点和Hugo、Eleventy这类静态站点生成器有点像，但区别在于Astro允许你在静态页面里嵌入真正的交互组件，而不是回到jQuery手写事件的老路。

在Astro中，每个.astro文件里的组件代码分为两部分：---里面的frontmatter部分（编译时执行，Node.js环境），以及模板部分（输出HTML）。frontmatter里可以写任意的JavaScript/TypeScript逻辑，比如拉取数据、计算日期、生成静态路径，这些代码只会在编译期跑一次，产物里不会保留任何影子。模板里的变量插值也全部在编译期完成，最终输出是纯字符串拼接的结果。

2.2 client指令：告诉Astro何时激活哪座岛屿

岛屿本身是“死”的，你得明确告诉Astro哪些组件需要水合、什么时候水合。这就是client:*指令的用途。指令写在组件标签上，Astro构建器看到指令后，才会为该组件生成独立的JavaScript chunk，并在满足条件时执行水合逻辑。

下面是我整理过的常用指令对照表：

这里有个常见误解：client:visible不是让你把组件放在页面底部然后“什么都不管”。Astro在实现上使用IntersectionObserver监听元素进入视口，但如果你把组件放在初始视口内，它很快就会触发水合。真正想做懒加载，需要在视觉上让组件离开首屏，或者配合CSS让它可以滚动进入。实测下来，client:idle和client:visible的触发时间差异不小，如果你的组件是可交互的广告位、评论区占位，client:visible更稳；如果是折叠面板这种大概率晚点才被点到的，client:idle能有效避开首屏加载高峰。

还有一点需要注意：client:only="react"需要显式指定框架名，因为Astro不知道你组件文件用的是哪个框架编译出来的。如果不指定，构建会报错。这个指令的典型场景是组件里有window、localStorage等浏览器API，但你在SSR时又没法保护环境，与其在组件内部挂typeof window === 'undefined'判断，不如直接声明“我只需要在浏览器端渲染”。

2.3 多框架共存：一座岛上插不同的旗子

Astro的另一个大胆设计是允许你在同一页面混用React、Vue、Svelte、Solid、Preact组件。这在传统SPA里几乎不可想象，因为每个框架都有自己的运行时和调度机制，混在一起要么体积爆炸，要么状态不同步。但Astro的岛屿架构天然适合混用：岛屿之间没有共享运行时，每个框架的脚本都隔离在自己那片小岛上，互不干扰。

实际操作中，你需要分别在astro.config.mjs里注册对应的框架集成：

// astro.config.mjs import { defineConfig } from 'astro/config'; import react from '@astrojs/react'; import vue from '@astrojs/vue'; import svelte from '@astrojs/svelte'; export default defineConfig({ integrations: [react(), vue(), svelte()], });

然后在.astro页面里这样混用：

--- import ReactCounter from '../components/ReactCounter.tsx'; import VueCounter from '../components/VueCounter.vue'; import SvelteCounter from '../components/SvelteCounter.svelte'; --- <ReactCounter client:load /> <VueCounter client:visible /> <SvelteCounter client:idle />

这三个组件各自编译成独立的脚本，水合时机也完全独立。我喜欢混用的一个真实场景是：主技术栈是React，但某个老项目留下了几个Vue的图表组件，不想重写。迁到Astro之后，直接把Vue组件像普通模块一样引入，加client:visible之后，它们工作得老老实实。代价是每个框架各自的运行时都单独打包，但既然它们只在自己岛屿上运行，这部分成本是显性的、可控的，不会像SPA那样你引入一个框架就要背负全站。

3. 用Astro搭建一个带交互岛屿的页面——从初始化到验证

3.1 项目初始化与目录结构设计

先说明一下环境。我写这篇文章时Astro最新稳定版是5.x，Node.js建议用20版本以上。初始化命令很简单：

# 创建项目（交互式CLI） npm create astro@latest my-island-site # 进入目录 cd my-island-site # 安装依赖 npm install # 本地开发 npm run dev

CLI会让你选择模板，新手选Basic就够。创建出来的目录结构大致是：

my-island-site/ ├── src/ │ ├── components/ # 岛屿组件放这里（.astro/.tsx/.vue/.svelte） │ ├── layouts/ # 页面布局骨架 │ ├── pages/ # 路由页面，文件路径即URL路径 │ └── content.config.ts # 内容集合配置（Astro 5.x） ├── public/ # 静态资源目录，直接复制到产物 ├── astro.config.mjs └── package.json

Astro的目录规范很有意思：src/pages下每个.astro或.md文件都会变成一个路由，文件路径就是URL路径。这在内容站点里效率极高，因为你想新增一个“关于我们”页面，只要新建src/pages/about.astro，刷新浏览器就能直接访问/about，不用手动注册路由。

3.2 写一个React岛屿组件并激活它

我现在创建两个文件来演示最核心的岛屿激活流程。第一个是React组件，用最简单的方式写一个计数器：

// src/components/Counter.tsx import { useState } from 'react'; export default function Counter() { const [count, setCount] = useState(0); return ( <div style={{ padding: '1rem', border: '1px solid #ddd' }}> <p>当前计数：{count}</p> <button onClick={() => setCount(c => c + 1)}>加一</button> </div> ); }

注意这里没有export const config之类的Astro专用标记，就是一个普通的React组件。接下来在页面里引入它，并决定它什么时候水合：

--- // src/pages/index.astro import Layout from '../layouts/Layout.astro'; import Counter from '../components/Counter.tsx'; --- <Layout title="岛屿架构演示"> <h1>岛屿架构实战</h1> <p>这一段是纯静态HTML，浏览器不需要加载任何JavaScript。</p> <Counter client:load /> <p>这一段同样是静态内容。</p> </Layout>

在开发模式下，npm run dev会启动Astro的开发服务器，页面加载后你会看到Counter组件正常交互。但我建议你用npm run build && npm run preview跑一次生产构建，再在浏览器里看Network面板。你会发现，请求资源里只有这个页面对应的HTML文件，以及Counter组件编译出的一个独立JS文件。页面上其余内容完全没有对应的脚本资源。

3.3 用Content Collections管理静态内容，把“海洋”做大

岛屿架构的另一个隐藏优势是，它和内容型站点天然契合。Astro 5.x把内容管理做成了内置功能，叫Content Collections（内容集合）。简单说，你可以定义一类内容的schema和存放目录，然后Astro会在编译期读取这些内容并生成静态页面。我自己的博客就是靠这个功能从零搭的，不用接任何CMS。

先配置一个内容集合，以博客文章为例：

// src/content.config.ts import { defineCollection, z } from 'astro:content'; const postsCollection = defineCollection({ type: 'content', schema: z.object({ title: z.string(), date: z.date(), tags: z.array(z.string()).default([]), description: z.string(), }), }); export const collections = { posts: postsCollection, };

然后在src/content/posts/下创建Markdown文件，例如hello-islands.md，frontmatter里写元信息，正文写内容。在页面里通过getCollection拿到所有文章数据：

--- import { getCollection } from 'astro:content'; const posts = await getCollection('posts'); --- <ul> {posts.map(post => ( <li> <a href={`/posts/${post.id}`}>{post.data.title}</a> <time datetime={post.data.date.toISOString()}> {post.data.date.toLocaleDateString()} </time> </li> ))} </ul>

Content Collections和岛屿架构的最佳结合点是：列表页是静态的，但列表上的交互行为是岛屿。比如你给每篇文章加一个“收藏”按钮，这个按钮就是一个client:visible的Svelte小岛；列表本身永远是纯HTML，浏览器不用运行任何框架代码。内容一多，这个优势会被无限放大。

3.4 构建产物检查：用数据验证岛屿是否按需加载

文章写到这里，光说不练是空的。我建议所有用Astro的人，在拿到一个页面之后都跑一次：

npm run build

构建完成后看dist/目录。你会发现每个页面都生成一个对应的index.html，而最终的JavaScript文件会按岛屿模块拆分。用grep或者编辑器搜索HTML里的<script>标签，能看到只有被标记了client:*的组件才带有type="module"的脚本引用。

我实际做过的优化实验里，一个包含30篇博客列表的页面，全静态内容时HTML大约是35KB，页面里放了一个React的“目录高亮”组件（client:visible）后，新增了一个4.8KB的脚本。整个页面加起来的传输成本比传统React应用渲染同样内容要低一个数量级。如果还嫌不够，再配合astro compress这类插件对HTML和静态资源做gzip/brotli压缩，静态站点通常能压到初始HTML 10KB以内，这几乎是传统SPA无法想象的首屏成本。

提示：验证岛屿是否被正确激活，最直接的方法是看Waterfall里的脚本加载时机。页面加载后，client:load的脚本会立即开始请求；client:visible的脚本只在对应DOM元素滚入视口前后才发起请求。如果某个组件在首屏就加载了你不希望它加载的脚本，检查一下标签上的指令是不是client:load。

4. 从实践里长出来的避坑经验——比文档更值钱的细节

4.1 水合时机选择的三个判断维度

文档只会告诉你client:load是页面加载后水合，client:idle是浏览器空闲后水合，但实际业务选择时，我建议按三个维度判断：

第一，这个交互是否影响首屏关键路径。导航栏、购物车入口、首屏搜索框、视频播放器，这些用户进入页面立刻可能操作的组件，直接上client:load。它们虽然会让首屏脚本多几十KB，但换来的响应速度是实打实的。第二，这个交互对用户的可见概率。页面底部“返回顶部”按钮、折叠面板、分页加载器，这些组件大概率在用户滚动之后才出现，用client:visible是最优选择。第三，这个交互是否可以延后到空闲时段。像评论区的“表情选择器”、文章页的“字号调整面板”，用户不一定用，用了也得等，那就client:idle。

我踩过最大的坑是：把一个图片懒加载组件标记成client:load，结果整个页面的LCP（最大内容绘制）被拖慢了。因为Astro虽然只加载这个组件本身的脚本，但脚本执行时会调用IntersectionObserver监听一组图片，这个注册过程本身让浏览器在解析HTML时就不得不处理一段JavaScript。后来改成client:visible，LCP立刻恢复了纯静态页面的水准。记住：岛屿指令不只是打包开关，它直接影响浏览器的加载和执行顺序，地图有多大，岛屿就应该在哪个时间点醒来。

4.2 岛屿通信：别指望一座岛知道另一座岛的内部状态

这是新手最容易犯的错误。既然Astro把组件隔离成独立岛屿，那React组件和Vue组件之间、甚至两个React组件之间，都无法像SPA那样直接通过全局Context或Redux共享状态。岛屿架构的设计哲学就是状态应该扁平化。

实践中有几种替代方案。如果两个岛屿之间需要共享少量数据，用>