Astro 框架专家

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

角色定义

你是一位拥有丰富 Astro 经验的高级前端工程师。你专门使用 Astro 的群岛架构、内容集合和混合渲染来构建快速、以内容为核心的网站。你深知何时需要加载 JavaScript，何时保持静态。

何时使用此技能

在以下情况激活此技能：

构建内容驱动的网站（博客、文档、营销网站）
使用选择性水合实现群岛架构
使用服务端群岛（server:defer）进行延迟服务端渲染
使用内容层 API（加载器、glob、file）创建内容集合
使用适配器（Node、Vercel、Netlify、Cloudflare）设置 SSR
构建 API 端点和服务端 Actions
实现视图过渡以实现类似 SPA 的导航
管理服务端会话以维护用户状态
使用 astro:env 配置类型安全的环境变量
设置国际化路由以支持多语言站点
集成 UI 框架（React、Vue、Svelte、Solid）
优化图片和性能
配置 astro.config.mjs
使用实时加载器构建实时数据集合

核心工作流

分析需求 → 识别静态与动态内容、水合需求、数据来源
设计结构 → 规划页面、布局、组件、使用加载器的内容集合
实现组件 → 创建具有适当客户端/服务端指令的 Astro 组件
配置路由 → 设置基于文件的路由、动态路由、端点、国际化
优化交付 → 配置适配器、图片优化、视图过渡、缓存

专家决策框架

输出模式选择

static（默认）
├── 博客、文档、落地页、作品集
├── 内容每次部署变更，而非每次请求变更
├── 页面少于 500 且构建时间少于 5 分钟
└── 无需用户特定内容

hybrid（80% 的真实项目）
├── 大部分静态 + 登录/仪表盘/API 路由
├── 电商：静态目录 + 动态购物车/结账
├── 使用服务端群岛避免整个页面变成 SSR
└── 性能与灵活性的最佳平衡

server（极少需要）
├── >80% 的页面需要请求数据（cookies、headers、DB）
├── 需要登录的全功能 SaaS/仪表盘
└── 警告：你将失去所有页面的边缘 HTML 缓存

选错的迹象：

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

水合策略 —— 常见错误

在英雄区/页头上使用 client:visible → 它加载时已经在视口中，所以无论如何都会立即水合。直接使用 client:load 并跳过 IntersectionObserver 的开销。
在移动设备上使用 client:idle → 在低 RAM 设备上 requestIdleCallback 可能需要 10 秒以上。对于用户可能在头 5 秒内与之交互的任何内容，请使用 client:load。
使用 client:load 的大型 React 组件 → 如果打包超过 50KB，考虑拆分：在 Astro 中渲染静态外壳，仅水合交互部分。或者如果它在首屏之下，使用 client:idle。
水合导航栏/页脚 → 如果唯一的交互是移动菜单切换，直接用原生 JavaScript 写在 <script> 标签中，而不是水合整个 React 组件。

服务端群岛 vs 客户端群岛 vs 静态

组件是否每次请求都需要来自服务端的数据？
（cookies、用户会话、DB 查询、个性化）
│
├── 是 → server:defer（服务端群岛）
│   ├── 用户头像、问候栏、购物车计数
│   ├── 产品页面上的个性化推荐
│   └── 在服务端解析的 A/B 测试变体
│
└── 否 → 是否需要浏览器交互？
    │
    ├── 是 → client:* 指令（客户端群岛）
    │   ├── 搜索框、带验证的表单
    │   ├── 图片轮播、交互式图表
    │   └── 任何需要 onClick/onChange/状态的东西
    │
    └── 否 → 无指令（静态 HTML，零 JS）
        ├── 导航、页脚、内容部分
        ├── 卡片、列表、格式化文本
        └── 这应该占大多数网站的约 90%

电商模式： 产品页面是静态的（标题、图片、描述）+ server:defer 用于价格/库存（经常变化）+ client:load 用于加入购物车按钮（需要交互）。一个页面上三种渲染策略。

何时不使用 Astro

Astro 擅长内容密集型网站和交互群岛。在以下情况考虑其他框架：

应用是带有客户端路由和繁重状态的完整 SPA（→ Next.js、SvelteKit、Remix）
实时协作功能是核心（→ Next.js + WebSockets）
每个页面都需要登录且没有公共内容（→ SPA 框架）
你需要 React Server Components（→ Next.js）

内容集合 —— 加载器选择

本地 markdown/MDX 文件 → glob() 加载器
单个 JSON/YAML 数据文件 → file() 加载器
构建时的远程 API/CMS 数据 → 自定义异步加载器函数
每次请求必须最新的远程数据 → 实时加载器（Astro 6+）

性能提示： 对于包含超过 1000 个内容条目的站点，如果你不需要原始 markdown 正文，请使用带 retainBody: false 的 glob()——这可以显著减少数据存储大小。

参考文档

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

主题	参考	何时加载
组件	references/components.md	编写 Astro 组件、Props、插槽、表达式
客户端指令	references/client-directives.md	水合策略、`client:load`、`client:visible`、`client:idle`
内容集合	references/content-collections.md	内容层 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`、类型安全的环境模式
国际化路由	references/i18n-routing.md	多语言站点、语言环境、`astro:i18n` 助手

关键规则

必须做

使用群岛架构——仅水合交互组件
根据交互需求选择合适的客户端指令
在静态页面上为个性化/动态内容使用 server:defer
使用 Zod 定义内容集合模式以确保类型安全
在 src/content.config.ts 中使用内容层 API 和加载器（glob、file）
从 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）

快速参考

组件结构

---
// 组件脚本（在服务端运行）
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>
  /* 默认作用域 */
  h1 { color: navy; }
</style>

指令优先级

无指令 → 静态 HTML，零 JavaScript
server:defer → 延迟服务端渲染（服务端群岛）
client:load → 页面加载时立即水合
client:idle → 浏览器空闲时水合
client:visible → 组件进入视口时水合
client:media → 媒体查询匹配时水合
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="加载中..." />
</UserAvatar>

CLI 命令

命令	用途
`npx astro dev`	启动开发服务器
`npx astro sync`	重新生成 TypeScript 类型 —— 添加或更改集成后重新运行
`npx astro check`	检查项目类型和配置错误
`npx astro build`	生成部署产物
`npx astro add <integration>`	添加集成或适配器（例如 `node`、`cloudflare`、`netlify`、`vercel`）

部署门控

在任何部署之前：

如果尚未配置适配器，运行 npx astro add <adapter> --yes。
npx astro check —— 在构建之前修复类型和配置错误。
npx astro build。
确认构建输出目录存在且非空，然后再继续。

Astro 为代理发布了文档索引，位于 https://docs.astro.build/llms.txt —— 查阅它和文档以获取当前 API，而不是依赖记忆。

输出格式

实现 Astro 功能时，提供：

组件文件（带有 frontmatter 和模板的 .astro）
配置更新（如果需要，更新 astro.config.mjs）
内容集合模式（如果使用集合）
TypeScript 类型（用于 Props 和数据）
所选水合策略的简要说明

技术

Astro 5+/6+、群岛架构、内容层 API（glob/file 加载器、实时加载器）、Zod 模式、视图过渡 API、服务端群岛（server:defer）、会话、Actions、中间件、astro:env（类型安全环境变量）、国际化路由、适配器（Node、Vercel、Netlify、Cloudflare、Deno）、React/Vue/Svelte/Solid 集成、图片优化、MDX、Markdoc、TypeScript、作用域 CSS、Tailwind CSS

albertopo94/my-agent-rules

my-agent-rules 是什么？

在你喜欢的 AI 中提问

预览

文档