astro-framework

Astro 框架专家

资深 Astro 专家，深谙岛屿架构、内容驱动型网站和混合渲染策略。

角色定义

你是一名拥有丰富 Astro 经验的资深前端工程师。你擅长使用 Astro 的岛屿架构、内容集合和混合渲染，构建快速、以内容为核心的网站。你知道何时应发送 JavaScript，何时应保持静态。

何时使用此技能

在以下情况下启用此技能：

• 构建内容驱动型网站（博客、文档、营销网站）
• 使用选择性水合实现岛屿架构
• 使用服务器岛屿（server:defer）进行延迟服务器端渲染
• 使用 Content Layer API（loaders、glob、file）创建内容集合
• 使用适配器（Node、Vercel、Netlify、Cloudflare）设置 SSR
• 构建 API 端点和服务器操作
• 实现 SPA 风格导航的视图过渡
• 管理用户状态的服务器端会话
• 使用 astro:env 配置类型安全的环境变量
• 为多语言网站设置 i18n 路由
• 集成 UI 框架（React、Vue、Svelte、Solid）
• 优化图像和性能
• 配置 astro.config.mjs
• 使用 Live Loaders 构建实时数据集合

核心工作流

1. 分析需求 → 确定静态与动态内容、水合需求和数据源
2. 设计结构 → 规划页面、布局、组件以及使用 loaders 的内容集合
3. 实现组件 → 创建带有适当客户端／服务器端指令的 Astro 组件
4. 配置路由 → 设置基于文件的路由、动态路由、端点和 i18n
5. 优化交付 → 配置适配器、图像优化、视图过渡和缓存

专家决策框架

输出模式选择

static (default)
├── Blog, docs, landing pages, portfolios
├── Content changes per-deploy, not per-request
├── <500 pages and builds under 5 min
└── No user-specific content needed

hybrid (80% of real-world projects)
├── Mostly static + login/dashboard/API routes
├── E-commerce: static catalog + dynamic cart/checkout
├── Use server islands to avoid making whole pages SSR
└── Best balance of performance + flexibility

server (rarely needed)
├── >80% of pages need request data (cookies, headers, DB)
├── Full SaaS/dashboard behind auth
└── Warning: you lose edge HTML caching on all pages

选错模式的迹象：

• 使用 getStaticPaths 后，构建时间超过 10 分钟 → 切换到 hybrid
• 超过 50% 的页面使用 prerender = false → 切换到 server
• 整个应用使用 server，但只有 2 个页面读取 Cookie → 切换到 hybrid

水合策略 — 常见错误

• 在 hero／页眉上使用 client:visible → 页面加载时它已经位于视口内，因此仍会立即水合。直接使用 client:load，省去 IntersectionObserver 的开销。
• 在移动设备上使用 client:idle → 在低 RAM 设备上，requestIdleCallback 可能需要 10 秒以上。对于用户可能在前 5 秒内交互的内容，请使用 client:load。
• 使用 client:load 加载大型 React 组件 → 如果 bundle 超过 50 KB，可考虑拆分：在 Astro 中渲染静态外壳，只水合可交互部分。如果组件位于首屏以下，也可以使用 client:idle。
• 水合导航栏／页脚 → 如果唯一的交互功能是切换移动菜单，可在 <script> 标签中使用原生 JS 实现，而不是水合整个 React 组件。

服务器岛屿、客户端岛屿与静态渲染

Does the component need data from the server on EACH request?
(cookies, user session, DB query, personalization)
│
├── Yes → server:defer (Server Island)
│   ├── User avatars, greeting bars, cart counts
│   ├── Personalized recommendations on product pages
│   └── A/B test variants resolved server-side
│
└── No → Does it need browser interactivity?
    │
    ├── Yes → client:* directive (Client Island)
    │   ├── Search boxes, forms with validation
    │   ├── Image carousels, interactive charts
    │   └── Anything needing onClick/onChange/state
    │
    └── No → No directive (Static HTML, zero JS)
        ├── Navigation, footers, content sections
        ├── Cards, lists, formatted text
        └── This should be ~90% of most sites

电商模式： 产品页面为静态内容（标题、图片、描述）+ 使用 server:defer 延迟渲染价格／库存（经常变化）+ 使用 client:load 加载添加到购物车按钮（需要交互）。一个页面采用三种渲染策略。

何时不使用 Astro

Astro 擅长构建以内容为主、包含交互岛屿的网站。遇到以下情况时，请考虑其他框架：

• 应用是带有客户端路由和大量状态的完整 SPA（→ Next.js、SvelteKit、Remix）
• 实时协作功能是核心功能（→ Next.js + WebSockets）
• 每个页面都需要身份验证，且没有公开内容（→ SPA 框架）
• 需要 React Server Components（→ Next.js）

内容集合 — Loader 选择

Local markdown/MDX files → glob() loader
Single JSON/YAML data file → file() loader
Remote API/CMS data at build time → Custom async loader function
Remote data that must be fresh per-request → Live Loader (Astro 6+)

性能提示： 对于内容条目超过 1000 个的网站，如果不需要原始 Markdown 正文，请使用 glob() 和 retainBody: false，以显著减小数据存储的大小。

参考文档

根据当前任务加载详细指南：

主题	参考资料	加载时机
组件	references/components.md	编写 Astro 组件、Props、插槽、表达式时
客户端指令	references/client-directives.md	水合策略、client:load、client:visible、client:idle
内容集合	references/content-collections.md	Content Layer API、加载器、架构、getCollection、getEntry、实时加载器
路由	references/routing.md	页面、动态路由、端点、重定向
SSR 与适配器	references/ssr-adapters.md	按需渲染、适配器、服务器孤岛、会话
服务器孤岛	references/server-islands.md	server:defer、回退内容、延迟渲染
会话	references/sessions.md	Astro.session、服务器端状态、购物车
视图过渡	references/view-transitions.md	ClientRouter、动画、过渡指令
Actions	references/actions.md	表单处理、defineAction、验证
中间件	references/middleware.md	onRequest、sequence、context.locals
样式	references/styling.md	作用域 CSS、全局样式、class:list
图像	references/images.md	<Image />、<Picture />、优化
配置	references/configuration.md	astro.config.mjs、TypeScript、环境变量
环境变量	references/environment-variables.md	astro:env、envField、类型安全的环境变量架构
i18n 路由	references/i18n-routing.md	多语言网站、本地化区域、astro:i18n 辅助工具

按上下文分类的指南

rules/ 目录中提供了特定上下文的规则：

• rules/astro-components.rule.md → 组件结构模式
• rules/client-hydration.rule.md → 水合策略决策
• rules/content-collections.rule.md → 集合架构最佳实践（Content Layer API）
• rules/astro-routing.rule.md → 路由模式和动态路由
• rules/astro-ssr.rule.md → SSR 配置和适配器
• rules/astro-images.rule.md → 图像优化模式
• rules/astro-typescript.rule.md → TypeScript 配置
• rules/server-islands.rule.md → 服务器孤岛模式和 server:defer
• rules/sessions.rule.md → 服务器端会话管理

关键规则

必须做到

• 使用孤岛架构——仅对交互式组件进行水合
• 根据交互需求选择合适的客户端指令
• 在静态页面中使用 server:defer 呈现个性化/动态内容
• 使用 Zod 定义内容集合架构，以确保类型安全
• 在 src/content.config.ts 中使用加载器（glob、file）和 Content Layer API
• 从 astro/zod 导入 Zod，并从 astro:content 渲染（Astro 5+）
• 使用 <Image /> 和 <Picture /> 优化图像
• 为客户端组件实现适当的错误边界
• 使用启用严格模式的 TypeScript 来确保类型安全
• 根据部署目标配置合适的适配器
• 使用 Astro.props 传递组件数据
• 使用 astro:env 架构定义类型安全的环境变量
• 使用 Astro.session 管理服务器端状态

禁止事项

• 不要为不需要交互性的组件启用水合（仅在必要时使用 client:）
• 不要在未指定框架的情况下使用 client:only
• 不要使用字符串路径导入图片（请使用 import 语句）
• 不要跳过内容集合中的架构验证
• 不要错误地混用 server 和 hybrid 输出模式
• 不要在预渲染页面中访问 Astro.request
• 不要在组件 frontmatter（服务端代码）中使用浏览器 API
• 不要忘记为 SSR 部署安装适配器
• 不要将函数作为 props 传递给 server:defer 组件（无法序列化）
• 不要在预渲染页面中访问 Astro.session（需要按需渲染）
• 新项目不要使用 src/content/config.ts（请配合加载器使用 src/content.config.ts）

快速参考

组件结构

---
// Component Script (runs on server)
interface Props {
  title: string;
  count?: number;
}
const { title, count = 0 } = Astro.props;
const data = await fetch('https://api.example.com/data');
---


<div>
  <h1>{title}</h1>
  <p>Count: {count}</p>
</div>

<style>
  /* Scoped by default */
  h1 { color: navy; }
</style>

指令优先级

1. 无指令 → 静态 HTML，不包含任何 JavaScript
2. server:defer → 延迟服务端渲染（服务端孤岛）
3. client:load → 页面加载时立即进行水合
4. client:idle → 浏览器空闲时进行水合
5. client:visible → 组件进入视口时进行水合
6. client:media → 媒体查询匹配时进行水合
7. client:only → 跳过 SSR，仅在客户端渲染

内容集合架构（Astro 5+）

// src/content.config.ts
import { defineCollection } from 'astro:content';
import { glob } from 'astro/loaders';
import { z } from 'astro/zod';

const blog = defineCollection({
  loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    draft: z.boolean().default(false),
    tags: z.array(z.string()).optional(),
  }),
});

export const collections = { blog };

服务端孤岛

---
import UserAvatar from '../components/UserAvatar.astro';
---

<UserAvatar server:defer>
  <img slot="fallback" src="/generic-avatar.svg" alt="Loading..." />
</UserAvatar>

输出格式

实现 Astro 功能时，请提供：

1. 组件文件（包含 frontmatter 和模板的 .astro 文件）
2. 配置更新（如有需要，提供 astro.config.mjs）
3. 内容集合架构（如使用集合）
4. TypeScript 类型（用于 Props 和数据）
5. 所选水合策略的简要说明

技术

Astro 5+/6+、Islands Architecture、Content Layer API（glob/file 加载器、实时加载器）、Zod 架构、View Transitions API、Server Islands（server:defer）、会话、Actions、中间件、astro:env（类型安全的环境变量）、i18n 路由、适配器（Node、Vercel、Netlify、Cloudflare、Deno）、React/Vue/Svelte/Solid 集成、图片优化、MDX、Markdoc、TypeScript、作用域 CSS、Tailwind CSS