Astro

🎯 为什么需要它

你想建一个内容驱动的网站（博客、文档站、营销页、作品集），但面对 Next.js 的复杂度和 React 生态的 JS 膨胀感到疲惫。你需要的是：写出的页面默认零 JS、性能开箱即用、同时还能在需要交互的地方用你熟悉的框架。

Astro 就是为此而生的。它是一个专注于内容驱动网站的 Web 框架，通过 Islands Architecture（岛屿架构）实现"默认零 JS，按需水合"的极致性能策略。

一句话定位

内容优先、零 JS 默认、按需交互的现代 Web 框架。

它解决的核心痛点

• JS 膨胀 — 传统 SPA 框架（React/Vue）整页水合，首屏加载大量无用 JS
• 框架锁定 — 一旦选定 React/Vue，整个项目都被绑定，无法混合使用
• 内容网站不需要 SPA — 博客、文档、营销页不需要客户端路由和状态管理
• SEO 和性能要求 — Core Web Vitals 直接影响搜索排名，静态 HTML 是最优解

✅ 核心优势

Client Directives（水合指令）

Astro 的核心机制是通过指令控制组件何时、如何加载 JS：

<!-- 默认：纯 HTML，无 JS -->
<MyComponent />

<!-- 页面加载时立即水合 -->
<ReactCounter client:load />

<!-- 组件进入视口时才水合 -->
<ImageCarousel client:visible />

<!-- 浏览器空闲时水合 -->
<ChatWidget client:idle />

<!-- 仅在客户端渲染（跳过 SSR） -->
<MapComponent client:only="react" />

⚡ 性能表现

构建性能

• 构建工具：Vite（开发）+ esbuild/rollup（生产）
• 开发 HMR：毫秒级热更新，Vite 的核心优势
• 构建速度：中大型站点（数百页）通常 5-15 秒完成构建

运行时性能

• 默认零 JS：纯内容页面（如博客文章）输出为纯 HTML+CSS，JS 体积为 0
• 按需加载：只有标记了 client:* 指令的组件才会发送 JS
• 并行水合：各岛屿独立加载，互不阻塞
• Core Web Vitals：Lighthouse 评分普遍 95+，在所有主流 SSG 中排名顶级

🚀 快速上手

Step 1：创建项目

npm create astro@latest my-site
cd my-site

交互式向导会引导你选择模板（空白 / 博客 / 文档等）和是否使用 TypeScript。

Step 2：项目结构

my-site/
  ├── src/
  │   ├── pages/          # 文件路由：每个 .astro/.md 文件是一个页面
  │   │   ├── index.astro
  │   │   └── about.md
  │   ├── components/     # 可复用组件（.astro / .tsx / .vue / .svelte）
  │   ├── layouts/        # 页面布局模板
  │   └── content/        # 内容集合（Markdown/MDX）
  │       └── blog/
  │           ├── post-1.md
  │           └── post-2.md
  ├── public/             # 静态资源（图片、字体等）
  ├── astro.config.mjs    # Astro 配置
  └── package.json

Step 3：编写 Astro 组件

---
// 组件脚本（服务端执行，不会发送到客户端）
const title = "Hello Astro"
const items = ["Fast", "Flexible", "Fun"]
---

<h1>{title}</h1>
<ul>
  {items.map(item => <li>{item}</li>)}
</ul>

<style>
  h1 { color: #ff5d01; }
</style>

Step 4：使用内容集合

// src/content.config.ts
import { defineCollection, z } from "astro:content"
const blog = defineCollection({
  type: "content",
  schema: z.object({
    title: z.string(),
    pubDate: z.date(),
    description: z.string(),
  }),
})
export const collections = { blog }

---
// src/pages/blog/[...slug].astro
import { getCollection } from "astro:content"
export async function getStaticPaths() {
  const posts = await getCollection("blog")
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }))
}
const { Content } = await render(Astro.props.post)
---
<article>
  <h1>{post.data.title}</h1>
  <Content />
</article>

Step 5：添加框架集成

# 添加 React 支持
npx astro add react

# 添加 Vue 支持
npx astro add vue

# 添加 Tailwind CSS
npx astro add tailwind

Step 6：开发与构建

# 开发模式（带 HMR）
npm run dev

# 构建静态站点
npm run build

# 预览构建结果
npm run preview

Step 7：部署

# 静态部署（默认 SSG）
# 直接将 dist/ 目录部署到任意静态托管

# SSR 部署（需要适配器）
npx astro add vercel    # Vercel
npx astro add netlify   # Netlify
npx astro add node      # Node.js 服务器

📦 适用场景

✅ 最佳使用场景

⚠️ 不太适合的场景

⚠️ 已知坑

🆚 竞品对比

选型建议

• 选 Astro：内容驱动网站，追求极致性能，团队有多框架背景，不想被 React 锁定
• 选 Next.js：需要复杂交互、认证、API 路由、全栈能力的 Web 应用
• 选 Hugo：超大规模内容站（万级页面），追求极致构建速度，不介意 Go 模板
• 选 Gatsby：已有 React 生态深度绑定，需要 GraphQL 数据层（但 2026 年新项目不推荐）

🌍 生态社区

项目数据

官方集成

社区资源

• 官方文档：docs.astro.build — 质量极高，有交互式示例
• Astro.new：浏览器内直接打开模板项目，零配置体验
• Discord 社区：活跃度极高，官方团队成员直接答疑
• Astro Jobs：astro.jobs — 专门的 Astro 职位平台

💡 引入评估

值不值得引入？

引入决策树

1. 你的网站是内容驱动的吗（博客/文档/营销/作品集）？→ 是 → 选 Astro
2. 你需要复杂客户端交互（实时协作/复杂表单/仪表盘）？→ 是 → 考虑 Next.js
3. 你需要极致构建速度 + 超大规模内容（万级页面）？→ 是 → 考虑 Hugo
4. 你想在需要交互的地方用 React/Vue/Svelte？→ 是 → Astro 依然支持（Islands）

🔗 相关链接

标签

📝 个人备注