astro

Name: astro
Author: briantbr

github.com/briantbr开发272 次安装34 周前更新

代码仓库

关于 astro

面向内容型网站开发者的 Astro 5.x 技能指南，涵盖渲染方式、多框架岛屿和常见生产实践。

主要功能

01默认不输出 JavaScript
02使用客户端指令进行水合
03支持 React、Vue 和 Svelte
04静态与服务器输出模式
05内容集合与图像优化

适用场景

01构建内容型网站
02为页面添加按需交互
03使用 Markdown 或 MDX 创建博客
04在服务器端渲染动态路由

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/briantbr/astro-best-practices-v6 --skill astro

安装后在 Claude Code 中输入/astro确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore

README.md

references/

environment-config.md

api-endpoints.md

middleware.md

content-collections.md

integrations.md

images.md

pagination.md

recipe-auth.md

recipe-blog.md

recipe-forms.md

recipe-dark-mode.md

recipe-i18n.md

ssr.md

recipe-seo.md

详细介绍

Astro 框架

Astro 5.x 框架，采用 Islands 架构，默认不包含 JavaScript，适用于构建快速、以内容为中心的网站。

核心原则

1. 默认不包含 JavaScript

除非显式添加客户端指令，否则 Astro 不会输出任何 JavaScript。


<Header />
<Footer />


<Counter client:idle />

规则：仅当组件需要钩子、状态或浏览器 API 时才使用客户端指令。

2. 客户端指令

指令	适用场景	行为
`client:load`	需要立即进行关键交互	页面加载时进行水合
`client:idle`	非关键交互	浏览器空闲时进行水合
`client:visible`	首屏以下的内容	滚动到视口内时进行水合
`client:media="(query)"`	响应式组件	媒体查询匹配时进行水合
`client:only="framework"`	SSR 时会出错	跳过 SSR，仅在客户端渲染

决策树：需要立即交互？→ client:load | 非关键交互？→ client:idle | 位于首屏以下？→ client:visible | 仅在移动端／桌面端显示？→ client:media | SSR 时会出错？→ client:only

3. 多框架支持

在同一个项目中混用 React、Vue 和 Svelte：

npx astro add react vue svelte

---
import ReactForm from './Form.jsx';
import VueChart from './Chart.vue';
import SvelteCounter from './Counter.svelte';
---
<ReactForm client:idle />
<VueChart client:visible />
<SvelteCounter client:load />

快速开始

npm create astro@latest my-project
cd my-project
npx astro add tailwind react
npm run dev

项目结构

src/
├── components/       # .astro, .jsx, .vue, .svelte
├── layouts/          # Page layouts
├── pages/            # File-based routing
│   └── blog/[slug].astro
├── content/          # Content Collections (Markdown/MDX)
│   └── blog/         # Collection folders
├── styles/           # Global CSS
└── content.config.ts # Content collections schema (Astro 5+)

配置

// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import react from '@astrojs/react';

export default defineConfig({
  site: 'https://example.com',
  output: 'static',  // or 'server'
  integrations: [tailwind(), react()],
});

输出模式（Astro 5）：

static - 博客、文档、营销网站（默认）。SSR 页面使用 export const prerender = false。
server - 所有页面均使用 SSR（需要适配器）

Astro 5 变更：output: 'hybrid' 已移除。现在 static 模式默认采用混合行为。

视图过渡

使用客户端路由器实现类似 SPA 的导航：

---
import { ClientRouter } from 'astro:transitions';
---
<html>
  <head>
    <ClientRouter />
  </head>
  <body><slot /></body>
</html>

注意：在 Astro 5 中，ViewTransitions 已重命名为 ClientRouter。

命令

npm run dev              # Start dev server (localhost:4321)
npm run build            # Build for production
npm run preview          # Preview production build
npx astro check          # TypeScript checks