astro

Astro

概览

Astro 是一个用于构建快速、以内容为中心的网站的一体化 Web 框架。它采用 Islands 架构，默认不发送任何 JavaScript，仅按需激活交互式组件。React、Svelte、Vue、Solid 和 Preact 的组件可以共存于同一个项目中。

适用场景： 以内容为驱动的网站（博客、文档、营销网站）、作品集、电子商务店面，以及大多数页面主要为静态页面且仅有少量独立交互区域的任何网站。

不适用场景： 高度交互的单页应用（仪表盘、实时协作工具），以及需要完全客户端路由、并在所有组件间共享全局状态的应用。

快速参考

模式	API / 指令	要点
内容集合	defineCollection({ loader, schema })	Zod 架构、glob/文件加载器、类型安全查询
查询集合	getCollection('blog')	返回类型化数组，支持筛选回调
单条目	getEntry('blog', 'my-post')	根据集合名称和条目 ID 获取
Island（加载时）	<Component client:load />	页面加载时立即进行水合
Island（空闲时）	<Component client:idle />	浏览器空闲时进行水合
Island（可见时）	<Component client:visible />	组件进入视口时进行水合
Island（仅客户端）	<Component client:only="react" />	跳过 SSR，仅在客户端渲染
视图过渡	<ClientRouter />	添加到 <head>，启用类似 SPA 的导航
持久化状态	transition:persist	在导航过程中保留 Island 状态
以编程方式导航	navigate(href)	从脚本执行客户端导航
静态输出	output: 'static'	构建时预渲染所有页面（默认）
服务端输出	output: 'server'	按需对所有页面进行服务端渲染
混合模式（选择启用 SSR）	output: 'static' + 每页设置 prerender = false	默认静态输出，可选择让单个页面启用 SSR
混合模式（选择启用静态）	output: 'server' + 每页设置 prerender = true	默认 SSR，可选择让单个页面启用静态输出
服务端 Island	<Component server:defer />	延迟静态页面中动态内容的服务端渲染
中间件	onRequest(context, next)	在每个路由之前运行，使用 sequence() 链接
Astro DB 表	defineTable({ columns })	使用列定义实现类型安全的 SQL
框架组件	导入 .jsx / .svelte / .vue	根据文件扩展名自动检测
集成	astro add react	用于添加框架适配器和工具的 CLI
渲染内容	const { Content } = await entry.render()	将 Markdown/MDX 编译为组件
动态路由	getStaticPaths() + 集合查询	根据集合条目生成页面
API 端点	export const GET: APIRoute	服务端渲染的 REST 端点
共享 Island 状态	nanostores	在不同框架边界之间共享响应式状态
环境变量	import.meta.env.PUBLIC_*	使用 PUBLIC_ 前缀表示客户端可访问的变量
过渡动画	transition:animate="slide"	initial、fade、slide、none
预取链接	data-astro-prefetch	hover、viewport、load 或 false
集合引用	reference('authors')	类型安全的跨集合关联
脚本重新执行	data-astro-rerun	每次视图过渡导航时重新运行 <script>
重定向	context.redirect(url, status)	从中间件或服务端页面重定向

常见错误

错误	正确做法
在 .astro 组件中添加 client: 指令	只有 UI 框架组件（React、Svelte、Vue）才接受 client:
到处使用 client:load	默认使用 client:idle 或 client:visible；谨慎使用 client:load
使用 client:only 时忘记框架字符串	必须指定框架：client:only="react"
在非 Astro 文件中混用框架组件	只有 .astro 文件才能组合来自多个框架的组件
对主要为静态的网站使用 output: 'server'	使用 output: 'static'，并为混合模式的各个页面设置 prerender = false
视图过渡时遗漏 <ClientRouter />	每个页面的 <head> 中都必须包含它（使用共享布局）
内容配置不在 src/content.config.ts	文件必须命名为 content.config.ts，并位于 src/ 根目录
未等待 getCollection() 调用	在 frontmatter 中始终对集合查询使用 await
在客户端脚本中从 astro:content 导入	内容 API 仅限服务端使用；将数据作为 props 传递给客户端组件
将中间件放在 src/middleware.ts 之外	中间件必须位于 src/middleware.ts 或 src/middleware/index.ts
将函数作为 props 传给岛屿	只有可序列化的数据才能跨越服务端与客户端的边界
使用 transition:persist，但页面不匹配	组件必须以相同的 persist 值出现在旧页面和新页面上
服务器/混合模式缺少适配器	安装适配器：npx astro add vercel（或 node、netlify 等）

委派

• 模式探索：使用 Explore Agent
• 构建配置：使用 Task Agent
• 代码审查：委派给 code-reviewer Agent

如果有 tailwind 技能，请将样式和 Tailwind CSS 配置委派给它。 如果有 vitest 技能，请将单元测试模式委派给它。 如果有 playwright 技能，请将端到端测试模式委派给它。 如果有 vite 技能，请将构建配置和 Vite 插件设置委派给它。 如果有 drizzle 技能，请将高级数据库查询模式委派给它。 如果有 sentry 技能，请将错误监控和可观测性设置委派给它。 如果有 pino-logging 技能，请将服务端日志配置委派给它。 如果有 tanstack-query 技能，请将客户端数据获取和缓存委派给它。

参考资料

• 内容集合、架构、加载器和查询
• 岛屿架构和水合指令
• 视图过渡和客户端导航
• 渲染模式：静态、服务器和混合
• 中间件模式和请求处理
• 框架组件集成（React、Svelte、Vue）
• Astro DB 架构、数据填充和查询