astro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Astro

Overview

概述

Astro is an all-in-one web framework for building fast, content-focused websites. It uses an islands architecture that ships zero JavaScript by default, hydrating only interactive components on demand. Components from React, Svelte, Vue, Solid, and Preact can coexist in a single project.

When to use: Content-driven sites (blogs, docs, marketing), portfolios, e-commerce storefronts, any site where most pages are primarily static with isolated interactive regions.

When NOT to use: Highly interactive single-page applications (dashboards, real-time collaboration tools), apps requiring full client-side routing with shared global state across all components.

Astro 是一款全能型Web框架，用于构建快速、以内容为核心的网站。它采用孤岛架构，默认情况下不发送任何JavaScript，仅按需 hydration 交互式组件。React、Svelte、Vue、Solid和Preact的组件可在同一个项目中共存。

适用场景： 内容驱动型网站（博客、文档、营销站点）、作品集、电商店铺前端，以及大部分页面以静态为主且仅包含孤立交互区域的任何网站。

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

Quick Reference

快速参考

Pattern	API / Directive	Key Points
Content collection	`defineCollection({ loader, schema })`	Zod schemas, glob/file loaders, type-safe queries
Query collection	`getCollection('blog')`	Returns typed array, supports filter callback
Single entry	`getEntry('blog', 'my-post')`	Fetch by collection name and entry ID
Island (load)	`<Component client:load />`	Hydrate immediately on page load
Island (idle)	`<Component client:idle />`	Hydrate when browser is idle
Island (visible)	`<Component client:visible />`	Hydrate when component enters viewport
Island (media)	`<Component client:media="(max-width: 768px)" />`	Hydrate on media query match
Island (client-only)	`<Component client:only="react" />`	Skip SSR, render only on client
View transitions	`<ClientRouter />`	Add to `<head>` , enables SPA-like navigation
Persist state	`transition:persist`	Maintain island state across navigations
Programmatic navigate	`navigate(href)`	Client-side navigation from scripts
Static output	`output: 'static'`	Pre-render all pages at build time (default)
Server output	`output: 'server'`	Server-render all pages on demand
Hybrid (opt-in SSR)	`output: 'static'` + per-page `prerender = false`	Static by default, opt individual pages into SSR
Hybrid (opt-in static)	`output: 'server'` + per-page `prerender = true`	SSR by default, opt individual pages into static
Server islands	`<Component server:defer />`	Defer server rendering for dynamic content in static
Middleware	`onRequest(context, next)`	Runs before every route, chain with `sequence()`
Astro DB table	`defineTable({ columns })`	Type-safe SQL with column definitions
Framework component	Import `.jsx` / `.svelte` / `.vue`	Auto-detected by file extension
Integration	`astro add react`	CLI to add framework adapters and tools
Render content	`const { Content } = await entry.render()`	Compile Markdown/MDX to component
Dynamic routes	`getStaticPaths()` + collection query	Generate pages from collection entries
API endpoint	`export const GET: APIRoute`	Server-rendered REST endpoints
Shared island state	`nanostores`	Reactive state across framework boundaries
Environment variables	`import.meta.env.PUBLIC_*`	`PUBLIC_` prefix for client-accessible vars
Transition animation	`transition:animate="slide"`	`initial` , `fade` , `slide` , `none`
Prefetch links	`data-astro-prefetch`	`hover` , `viewport` , `load` , or `false`
Collection reference	`reference('authors')`	Type-safe cross-collection relations
Script re-execution	`data-astro-rerun`	Re-run `<script>` on every view transition navigation
Redirect	`context.redirect(url, status)`	Redirect from middleware or server pages

模式	API / 指令	核心要点
内容集合	`defineCollection({ loader, schema })`	Zod模式、glob/文件加载器、类型安全查询
查询集合	`getCollection('blog')`	返回类型化数组，支持过滤回调
单条条目	`getEntry('blog', 'my-post')`	按集合名称和条目ID获取内容
孤岛（立即加载）	`<Component client:load />`	页面加载时立即进行hydrate
孤岛（空闲时加载）	`<Component client:idle />`	浏览器空闲时进行hydrate
孤岛（可见时加载）	`<Component client:visible />`	组件进入视口时进行hydrate
孤岛（媒体查询触发）	`<Component client:media="(max-width: 768px)" />`	匹配媒体查询时进行hydrate
孤岛（仅客户端）	`<Component client:only="react" />`	跳过SSR，仅在客户端渲染
视图过渡	`<ClientRouter />`	添加至 `<head>` 中，实现类SPA导航
状态持久化	`transition:persist`	在导航过程中保持孤岛状态
编程式导航	`navigate(href)`	从脚本中触发客户端导航
静态输出	`output: 'static'`	构建时预渲染所有页面（默认设置）
服务端输出	`output: 'server'`	按需服务端渲染所有页面
混合模式（可选SSR）	`output: 'static'` + 单页面 `prerender = false`	默认静态渲染，为单个页面开启SSR
混合模式（可选静态）	`output: 'server'` + 单页面 `prerender = true`	默认SSR，为单个页面开启静态渲染
服务端孤岛	`<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 endpoints
孤岛共享状态	`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)`	从中间件或服务端页面进行重定向

Common Mistakes

常见错误

Mistake	Correct Pattern
Adding `client:` directive to `.astro` components	Only UI framework components (React, Svelte, Vue) accept `client:`
Using `client:load` everywhere	Default to `client:idle` or `client:visible` ; use `client:load` sparingly
Forgetting framework string with `client:only`	Must specify framework: `client:only="react"`
Mixing framework components in non-Astro files	Only `.astro` files can compose components from multiple frameworks
Using `output: 'server'` for mostly static sites	Use `output: 'static'` with per-page `prerender = false` for hybrid
Omitting `<ClientRouter />` for view transitions	Must be in `<head>` of every page (use shared layout)
Content config not at `src/content.config.ts`	File must be named `content.config.ts` in `src/` root
Not awaiting `getCollection()` calls	Always `await` collection queries in frontmatter
Importing from `astro:content` in client scripts	Content APIs are server-only; pass data as props to client components
Placing middleware outside `src/middleware.ts`	Middleware must be at `src/middleware.ts` or `src/middleware/index.ts`
Passing functions as props to islands	Only serializable data crosses the server/client boundary
Using `transition:persist` without matching pages	Component must appear on both old and new page with same persist value
Missing adapter for server/hybrid mode	Install an adapter: `npx astro add vercel` (or node, netlify, etc.)

错误操作	正确做法
向 `.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()` 调用完成	必须在前置代码中始终 `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等）

Delegation

委托

Pattern discovery: Use
```
Explore
```
agent
Build configuration: Use
```
Task
```
agent
Code review: Delegate to
```
code-reviewer
```
agent

If the
tailwind
skill is available, delegate styling and Tailwind CSS configuration to it. If the
vitest
skill is available, delegate unit testing patterns to it. If the
playwright
skill is available, delegate end-to-end testing patterns to it. If the
vite
skill is available, delegate build configuration and Vite plugin setup to it. If the
drizzle
skill is available, delegate advanced database query patterns to it. If the
sentry
skill is available, delegate error monitoring and observability setup to it. If the
pino-logging
skill is available, delegate server-side logging configuration to it. If the
tanstack-query
skill is available, delegate client-side data fetching and caching to it.

模式探索：使用
```
Explore
```
agent
构建配置：使用
```
Task
```
agent
代码审查：委托给
```
code-reviewer
```
agent

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

References

参考

Content collections, schemas, loaders, and querying
Island architecture and hydration directives
View transitions and client-side navigation
Rendering modes: static, server, and hybrid
Middleware patterns and request handling
Framework component integration (React, Svelte, Vue)
Astro DB schema, seeding, and queries

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