astro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro

Astro is a web framework popularized for "Islands Architecture". It ships zero JavaScript to the client by default, hydrating only the interactive parts. Astro 5 (2025) introduces Server Islands.

Astro 是一款因“孤岛架构（Islands Architecture）”而广受关注的 Web 框架。默认情况下，它不会向客户端发送任何 JavaScript，仅对交互式部分进行水合。Astro 5（2025版）引入了 Server Islands（服务端孤岛）功能。

When to Use

适用场景

Content Sites: Blogs, Documentation, Marketing sites.
Multi-Framework: Use React, Vue, and Svelte components on the same page.
Performance: Hard to beat for static content.

内容类网站：博客、文档站、营销网站。
多框架兼容：可在同一页面中使用 React、Vue 和 Svelte 组件。
性能优先：在静态内容场景下性能表现优异。

Quick Start

快速开始

astro

---
// Server-side code (Frontmatter) runs at build/request time
const data = await fetch('https://api.myjson.com').then(r => r.json());
---

<html>
  <body>
    <h1>{data.title}</h1>
    <!-- Client Directive: This React component hydrates on load -->
    <MyReactComponent client:load />

    <!-- This Svelte component hydrates only when visible -->
    <MySvelteComponent client:visible />
  </body>
</html>

astro

---
// 服务端代码（Frontmatter）在构建/请求时运行
const data = await fetch('https://api.myjson.com').then(r => r.json());
---

<html>
  <body>
    <h1>{data.title}</h1>
    <!-- 客户端指令：该React组件在加载时进行水合 -->
    <MyReactComponent client:load />

    <!-- 该Svelte组件仅在可见时进行水合 -->
    <MySvelteComponent client:visible />
  </body>
</html>

Core Concepts

核心概念

Islands Architecture

孤岛架构（Islands Architecture）

The page is static HTML. Interactive widgets are "islands" floating in it. They hydrate independently.

页面主体为静态 HTML，交互式部件是漂浮在其中的“孤岛”，它们可独立进行水合。

Server Islands (Astro 5)

Server Islands（Astro 5）

Async islands. The page loads instantly (static), and a specific island (e.g., "User Profile") loads asynchronously from the server and fades in.

异步孤岛。页面会立即加载（静态内容），而特定孤岛（如“用户资料”）会从服务端异步加载并淡入显示。

Content Collections

内容集合（Content Collections）

Type-safe way to manage Markdown/MDX content.

const blogCollection = defineCollection({
  schema: z.object({ title: z.string(), date: z.date() }),
});

一种类型安全的 Markdown/MDX 内容管理方式。

const blogCollection = defineCollection({
  schema: z.object({ title: z.string(), date: z.date() }),
});

Best Practices (2025)

2025年最佳实践

Do:

Use Server Islands: For dynamic personalization (e.g., "Logged in as Jeevan") without forcing the whole page to be dynamic (SSR).
Use
<Image />
: Astro's optimized image component is essential for LCP.
Mix Frameworks: Don't be afraid to use React for a complex search bar and Svelte for a simple toggle on the same site.

Don't:

Don't use for complex dashboards: While possible (Hybrid Rendering), Next.js or Remix are often better suited for highly dynamic, authenticated apps.

推荐做法：

使用 Server Islands：用于实现动态个性化内容（如“当前登录用户：Jeevan”），无需将整个页面设为动态（SSR）。
使用
<Image />
组件：Astro 的优化图片组件对提升最大内容绘制（LCP）至关重要。
混合使用多框架：无需顾虑在同一网站中，用 React 实现复杂搜索栏，同时用 Svelte 实现简单切换组件。

不推荐做法：

不要用于复杂仪表盘：虽然可以通过混合渲染实现，但对于高度动态、需要身份验证的应用，Next.js 或 Remix 通常是更合适的选择。

References

参考资料

Astro Documentation

Astro 官方文档