Astro Web 框架
选择性阅读规则
从以下文件开始:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
然后,仅加载与用户实际任务匹配的继承文档、脚本、资源或示例。
概述
Astro 是一个专为内容丰富的网站设计的 Web 框架——博客、文档、作品集、营销网站和电子商务。其核心创新是孤岛架构:默认情况下,Astro 不向浏览器发送任何 JavaScript。交互式组件会被有选择地水合为独立的“孤岛”。Astro 支持在同一个项目中同时使用 React、Vue、Svelte、Solid 和其他 UI 框架,让您可以为每个组件选择合适的工具。
何时使用此技能
- 当构建博客、文档网站、营销页面或作品集时使用
- 当性能与核心 Web 指标是最高优先级时使用
- 当项目内容繁重,包含大量 Markdown 或 MDX 文件时使用
- 当需要 SSG(静态)输出,并带有用于动态路由的可选 SSR 时使用
- 当用户询问
.astro文件、Astro.props、内容集合或client:指令时使用
工作原理
步骤 1:项目设置
npm create astro@latest my-site
cd my-site
npm install
npm run dev
根据需要添加集成:
npx astro add tailwind # Tailwind CSS
npx astro add react # React 组件支持
npx astro add mdx # MDX 支持
npx astro add sitemap # 自动生成 sitemap.xml
npx astro add vercel # Vercel SSR 适配器
项目结构:
src/
pages/ ← 基于文件的路由(.astro, .md, .mdx)
layouts/ ← 可重用的页面壳
components/ ← UI 组件(.astro, .tsx, .vue 等)
content/ ← 类型安全的内容集合(Markdown/MDX)
styles/ ← 全局 CSS
public/ ← 静态资源(原样复制)
astro.config.mjs ← 框架配置
步骤 2:Astro 组件语法
.astro 文件顶部有一个代码栅栏(仅限服务端),下方是模板:
---
// src/components/Card.astro
// 此代码块仅在服务端运行——绝不会在浏览器中运行
interface Props {
title: string;
href: string;
description: string;
}
const { title, href, description } = Astro.props;
---
<article class="card">
<h2><a href={href}>{title}</a></h2>
<p>{description}</p>
</article>
<style>
/* 自动作用于此组件 */
.card { border: 1px solid #eee; padding: 1rem; }
</style>
步骤 3:基于文件的页面与路由
src/pages/index.astro → /
src/pages/about.astro → /about
src/pages/blog/[slug].astro → /blog/:slug (动态)
src/pages/blog/[...path].astro → /blog/* (通配)
使用 getStaticPaths 的动态路由:
---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
const posts = await getCollection('blog');
return posts.map(post => ({
params: { slug: post.slug },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await post.render();
---
<h1>{post.data.title}</h1>
<Content />
步骤 4:内容集合
内容集合为您提供对 Markdown 和 MDX 文件的类型安全访问:
// src/content/config.ts
import { z, defineCollection } from 'astro:content';
const blog = defineCollection({
type: 'content',
schema: z.object({
title: z.string(),
date: z.coerce.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';
const posts = (await getCollection('blog'))
.filter(p => !p.data.draft)
.sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---
<ul>
{posts.map(post => (
<li>
<a href={`/blog/${post.slug}`}>{post.data.title}</a>
<time>{post.data.date.toLocaleDateString()}</time>
</li>
))}
</ul>
步骤 5:孤岛——选择性水合
默认情况下,UI 框架组件会渲染为静态 HTML,不带任何 JavaScript。使用 client: 指令来水合:
---
import Counter from '../components/Counter.tsx'; // React 组件
import VideoPlayer from '../components/VideoPlayer.svelte';
---
<!-- 静态 HTML — 不向浏览器发送 JavaScript -->
<Counter initialCount={0} />
<!-- 页面加载时立即水合 -->
<Counter initialCount={0} client:load />
<!-- 当组件滚动到视口时水合 -->
<VideoPlayer src="/demo.mp4" client:visible />
<!-- 仅在浏览器空闲时水合 -->
<Analytics client:idle />
<!-- 仅在特定媒体查询下水合 -->
<MobileMenu client:media="(max-width: 768px)" />
步骤 6:布局
---
// src/layouts/BaseLayout.astro
interface Props {
title: string;
description?: string;
}
const { title, description = 'My Astro Site' } = Astro.props;
---
<html lang="en">
<head>
<meta charset="utf-8" />
<title>{title}</title>
<meta name="description" content={description} />
</head>
<body>
<nav>...</nav>
<main>
<slot /> <!-- 页面内容在此渲染 -->
</main>
<footer>...</footer>
</body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---
<BaseLayout title="About Us">
<h1>About Us</h1>
<p>Welcome to our company...</p>
</BaseLayout>
步骤 7:SSR 模式(按需渲染)
通过设置适配器启用 SSR:
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';
export default defineConfig({
output: 'hybrid', // 'static' | 'server' | 'hybrid'
adapter: vercel(),
});
使用 export const prerender = false 将单个页面设置为 SSR。
示例
示例 1:带 RSS 订阅的博客
// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';
export async function GET(context) {
const posts = await getCollection('blog');
return rss({
title: 'My Blog',
description: 'Latest posts',
site: context.site,
items: posts.map(post => ({
title: post.data.title,
pubDate: post.data.date,
link: `/blog/${post.slug}/`,
})),
});
}
示例 2:API 端点 (SSR)
// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';
export const POST: APIRoute = async ({ request }) => {
const { email } = await request.json();
if (!email) {
return new Response(JSON.stringify({ error: 'Email required' }), {
status: 400,
headers: { 'Content-Type': 'application/json' },
});
}
await addToNewsletter(email);
return new Response(JSON.stringify({ success: true }), { status: 200 });
};
示例 3:作为孤岛的 React 组件
// src/components/SearchBox.tsx
import { useState } from 'react';
export default function SearchBox() {
const [query, setQuery] = useState('');
const [results, setResults] = useState([]);
async function search(e: React.FormEvent) {
e.preventDefault();
const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
setResults(data);
}
return (
<form onSubmit={search}>
<input value={query} onChange={e => setQuery(e.target.value)} />
<button type="submit">Search</button>
<ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
</form>
);
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- 立即水合——此孤岛是可交互的 -->
<SearchBox client:load />
最佳实践
- ✅ 保持大多数组件为静态
.astro文件——只水合那些必须交互的组件 - ✅ 对所有 Markdown/MDX 内容使用内容集合——可以获得类型安全和自动验证
- ✅ 对于首屏以下的组件,优先使用
client:visible而非client:load,以减少初始 JavaScript - ✅ 使用
import.meta.env来管理环境变量——用PUBLIC_前缀标记公开变量 - ✅ 从
astro:transitions添加<ViewTransitions />,以实现平滑的页面导航,无需完整的 SPA - ❌ 不要在每一个组件上都使用
client:load——这会破坏 Astro 的性能优势 - ❌ 不要将秘密信息放入会在面向客户端的模板中使用的
.astro文件前端内容中 - ❌ 在静态模式下,不要跳过动态路由的
getStaticPaths——否则构建会失败
安全与注意事项
.astro文件中的前端内容代码仅在服务端运行,绝不会暴露给浏览器。- 仅对非敏感值使用
import.meta.env.PUBLIC_*。私有环境变量(无PUBLIC_前缀)绝不会发送到客户端。 - 使用 SSR 模式时,在数据库查询或 API 调用之前,验证所有
Astro.request的输入。 - 在使用
set:html渲染用户提供的内容之前,务必进行清理——它会绕过自动转义。
常见陷阱
-
问题: React/Vue 组件的 JavaScript 未在浏览器中运行 解决方案: 添加
client:指令(client:load、client:visible等)——没有它,组件将仅渲染为静态 HTML。 -
问题: 开发期间内容更新后
getStaticPaths的数据过时 解决方案: Astro 的开发服务器会监听内容文件——如果content/config.ts的更改未反映,请重启。 -
问题:
Astro.props的类型是any——没有自动完成 解决方案: 在前端内容中定义一个Props接口或类型,Astro 会自动推断它。 -
问题: 来自
.astro组件的 CSS 影响到了其他组件 解决方案:.astro<style>标签中的样式会自动作用域化。仅当有意针对子元素时,才使用:global()。
相关技能
@sveltekit— 当需要一个具有响应式 UI 的全栈框架时(对比 Astro 的内容专注)@nextjs-app-router-patterns— 当需要一个以 React 为首的全栈框架时@tailwind-patterns— 使用 Tailwind CSS 为 Astro 站点添加样式@progressive-web-app— 为 Astro 站点添加 PWA 功能
限制
- 仅当任务明确符合上述范围时使用此技能。
- 不要将输出视为环境特定验证、测试或专家审查的替代品。
- 如果缺少所需的输入、权限、安全边界或成功标准,请停下来并要求澄清。