何时使用

落地页和营销网站
公司官网
内容密集型网站（博客、文档）
任何 SEO 和性能至关重要的项目
基本为静态的网站，仅需少量交互
需要快速首屏加载和良好 Core Web Vitals 的网站

不适用于完整 Web 应用——交互式应用（仪表盘、CRUD 应用、实时应用）请使用 vue-frontend。

关键规则

默认零 JavaScript——Astro 不会输出任何 JavaScript，除非你添加客户端指令
始终使用 TypeScript——与所有 Vera Sesiom 项目一致，严格模式
对结构化内容使用 Content Collections——博客文章、文档、案例研究
Islands 架构——仅在需要交互的地方使用 Vue/React 组件
默认静态输出 (SSG)——仅在需要动态内容时使用 SSR
使用 Tailwind CSS 进行样式设计——与 Vue 前端一致
Screaming Architecture——文件夹命名应体现领域，而非框架

决策标准：Astro vs Vue

何时使用 Astro	何时使用 Vue
落地页、营销网站	网页应用（仪表盘、管理后台）
内容密集型（博客、文档）	高度交互的 UI
SEO 至关重要	需要实时功能
大部分为静态内容	复杂状态管理
最小交互（表单、轮播）	完整的 SPA 导航
零 JS 是一个特性	Vue 生态的优势重要

规则：如果网站内容是供人阅读 → 使用 Astro。如果是供人使用的应用 → 使用 Vue。

项目结构（Screaming Architecture）

apps/landing/   (或 apps/website/)
├── src/
│   ├── pages/                    # 基于文件的路由 (.astro 文件)
│   │   ├── index.astro           # 首页
│   │   ├── about.astro           # 关于页面
│   │   ├── pricing.astro         # 定价页面
│   │   ├── blog/
│   │   │   ├── index.astro      # 博客列表
│   │   │   └── [slug].astro      # 博客文章（动态）
│   │   └── contact.astro
│   ├── layouts/                  # 页面布局
│   │   ├── BaseLayout.astro      # 基础 HTML 结构
│   │   ├── BlogLayout.astro      # 博客文章布局
│   │   └── LandingLayout.astro   # 落地页布局
│   ├── components/               # Astro 组件（默认静态）
│   │   ├── sections/             # 页面区块
│   │   │   ├── Hero.astro
│   │   │   ├── Features.astro
│   │   │   ├── Pricing.astro
│   │   │   ├── Testimonials.astro
│   │   │   └── CTA.astro
│   │   ├── ui/                   # 可复用的 UI 原子组件
│   │   │   ├── Button.astro
│   │   │   ├── Card.astro
│   │   │   ├── Badge.astro
│   │   │   └── Input.astro
│   │   └── interactive/          # Vue/React 交互岛（Islands）
│   │       ├── ContactForm.vue   # 带验证的表单
│   │       ├── Carousel.vue      # 图片轮播
│   │       └── MobileMenu.vue    # 移动端导航
│   ├── content/                  # 内容集合
│   │   ├── blog/                 # Markdown/MDX 博客文章
│   │   │   ├── post-1.md
│   │   │   └── post-2.mdx
│   │   └── config.ts             # 集合架构 (Zod)
│   ├── styles/                   # 全局样式
│   │   └── global.css            # Tailwind 导入
│   ├── assets/                   # 优化后的图片、字体
│   │   ├── images/
│   │   └── fonts/
│   └── utils/                    # 辅助函数
│       ├── date-format.ts
│       └── seo.ts
├── public/                       # 静态资源（不经过处理）
│   ├── favicon.ico
│   ├── robots.txt
│   └── fonts/
├── astro.config.mjs              # Astro 配置
├── tailwind.config.mjs           # Tailwind 配置
├── tsconfig.json
└── package.json

Astro 组件模式

每个 .astro 文件包含两部分：frontmatter（服务端）和模板 (HTML)。

---
// src/components/ui/Button.astro
// Frontmatter：在服务端运行，没有浏览器端 JavaScript

export interface Props {
  variant?: 'primary' | 'secondary' | 'outline'
  size?: 'sm' | 'md' | 'lg'
  href?: string
}

const {
  variant = 'primary',
  size = 'md',
  href,
  ...rest
} = Astro.props

const baseClasses = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors'
const variantClasses = {
  primary: 'bg-blue-600 text-white hover:bg-blue-700',
  secondary: 'bg-gray-100 text-gray-900 hover:bg-gray-200',
  outline: 'border-2 border-blue-600 text-blue-600 hover:bg-blue-50'
}
const sizeClasses = {
  sm: 'px-3 py-1.5 text-sm',
  md: 'px-4 py-2 text-base',
  lg: 'px-6 py-3 text-lg'
}

const classes = `${baseClasses} ${variantClasses[variant]} ${sizeClasses[size]}`
---

{href ? (
  <a href={href} class={classes} {...rest}>
    <slot />
  </a>
) : (
  <button class={classes} {...rest}>
    <slot />
  </button>
)}

关键点：

Frontmatter 在构建时（或 SSR 的请求时）运行
无需 export default——模板本身就是导出
使用 <slot /> 渲染子内容
通过 TypeScript 接口定义 Props 类型

布局模式

---
// src/layouts/BaseLayout.astro
import Nav from '../components/Nav.astro'
import Footer from '../components/Footer.astro'

export interface Props {
  title: string
  description?: string
  image?: string
}

const { title, description = '', image = '/og-default.png' } = Astro.props
const canonicalURL = new URL(Astro.url.pathname, Astro.site)
---

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link rel="canonical" href={canonicalURL} />
    <title>{title}</title>
    <meta name="description" content={description} />
    
    <!-- OpenGraph -->
    <meta property="og:title" content={title} />
    <meta property="og:description" content={description} />
    <meta property="og:image" content={image} />
    <meta property="og:url" href={canonicalURL} />
    <meta property="og:type" content="website" />
    
    <!-- Twitter -->
    <meta name="twitter:card" content="summary_large_image" />
    
    <slot name="head" />
  </head>
  <body class="bg-white text-gray-900 antialiased">
    <Nav />
    <main>
      <slot />
    </main>
    <Footer />
  </body>
</html>

使用方式：

---
// src/pages/index.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import Hero from '../components/sections/Hero.astro'
---

<BaseLayout title="Vera Sesiom - Software Development" description="We build software that matters.">
  <Hero />
</BaseLayout>

Content Collection 模式

使用 Zod 架构验证结构化内容。

// src/content/config.ts
import { defineCollection, z } from 'astro:content'

const blogCollection = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    description: z.string(),
    pubDate: z.coerce.date(),
    updatedDate: z.coerce.date().optional(),
    author: z.string().default('Vera Sesiom'),
    image: z.object({
      url: z.string(),
      alt: z.string()
    }).optional(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false)
  })
})

export const collections = {
  blog: blogCollection
}

---
title: "为什么我们选择 Astro 构建 Landing Pages"
description: "性能和开发体验至关重要。以下是 Astro 成为我们内容网站首选的原因。"
pubDate: 2024-01-15
author: "技术负责人"
image:
  url: "/images/blog/astro-landing.jpg"
  alt: "现代网站上的 Astro Logo"
tags: ["astro", "performance", "architecture"]
---

内容写在这里...

---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.astro'

const posts = (await getCollection('blog'))
  .filter(post => !post.data.draft)
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
---

<BaseLayout title="Blog" description="来自 Vera Sesiom 的最新文章">
  <h1>Blog</h1>
  <ul>
    {posts.map(post => (
      <li>
        <a href={`/blog/${post.slug}`}>
          <h2>{post.data.title}</h2>
          <p>{post.data.description}</p>
          <time>{post.data.pubDate.toLocaleDateString()}</time>
        </a>
      </li>
    ))}
  </ul>
</BaseLayout>

---
// src/pages/blog/[slug].astro
import { getCollection } from 'astro:content'
import BaseLayout from '../../layouts/BaseLayout.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()
---

<BaseLayout title={post.data.title} description={post.data.description}>
  <article>
    <header>
      <h1>{post.data.title}</h1>
      <time>{post.data.pubDate.toLocaleDateString()}</time>
      <p>作者：{post.data.author}</p>
    </header>
    <Content />
  </article>
</BaseLayout>

Islands 架构 (Vue 组件)

交互式组件仅在需要时输出 JavaScript。使用客户端指令控制水合（Hydration）。

<!-- src/components/interactive/ContactForm.vue -->
<script setup lang="ts">
import { ref, computed } from 'vue'

const form = ref({
  name: '',
  email: '',
  message: ''
})

const errors = ref<Record<string, string>>({})

const isValid = computed(() => {
  return form.value.name && 
         form.value.email.includes('@') && 
         form.value.message.length > 10
})

async function submitForm() {
  if (!isValid.value) return
  
  // 提交到 API
  const response = await fetch('/api/contact', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(form.value)
  })
  
  if (response.ok) {
    // 处理成功
    form.value = { name: '', email: '', message: '' }
  }
}
</script>

<template>
  <form @submit.prevent="submitForm" class="space-y-4">
    <div>
      <label for="name">Name</label>
      <input v-model="form.name" type="text" id="name" required />
    </div>
    <div>
      <label for="email">Email</label>
      <input v-model="form.email" type="email" id="email" required />
    </div>
    <div>
      <label for="message">Message</label>
      <textarea v-model="form.message" id="message" rows="4" required />
    </div>
    <button type="submit" :disabled="!isValid">
      Send Message
    </button>
  </form>
</template>

在 Astro 中使用：

---
// src/pages/contact.astro
import BaseLayout from '../layouts/BaseLayout.astro'
import ContactForm from '../components/interactive/ContactForm.vue'
---

<BaseLayout title="Contact Us">
  <h1>Get in Touch</h1>
  <p>We'd love to hear from you.</p>
  
  <!-- client:visible = 当滚动到视口时才水合（最佳实践） -->
  <ContactForm client:visible />
</BaseLayout>

客户端指令决策树

指令	何时使用	JS 何时加载
无指令	静态内容，无需交互	零 JS
`client:visible`	首屏下方交互（表单、轮播）—— 默认	滚动到视口时
`client:load`	首屏关键交互	立即加载
`client:idle`	非关键增强（分析、聊天）	页面空闲后
`client:media`	根据断点条件加载（移动端导航）	媒体查询匹配时
`client:only`	SPA 类组件（跳过 SSR）	立即加载，无 SSR

最佳实践：

默认使用无指令——纯静态
需要交互时默认使用 client:visible
谨慎使用 client:load——仅用于首屏关键组件
使用 client:idle 处理非阻塞增强

---
<!-- 良好示例 -->
import Hero from './Hero.astro'                    <!-- 静态，无 JS -->
import Carousel from './Carousel.vue'             
import MobileMenu from './MobileMenu.vue'         
import Chat from './Chat.vue'                     
import Stats from './Stats.astro'                  <!-- 静态计数器 = CSS -->

<Hero />                                          <!-- 静态，无需水合 -->
<Carousel client:visible />                       <!-- 可见时水合 -->
<MobileMenu client:media="(max-width: 768px)" />  <!-- 仅移动端 -->
<Chat client:idle />                               <!-- 页面空闲后加载 -->
<Stats />                                          <!-- 纯 CSS 动画，无需 JS -->

图片优化

使用 astro:assets 实现自动优化。

---
// src/pages/index.astro
import { Image } from 'astro:assets'
import heroImage from '../assets/images/hero.png'
---

<Image 
  src={heroImage} 
  alt="Hero image" 
  width={800} 
  height={600}
  loading="lazy"
  format="webp"
/>

对于来自 CMS 或外部来源的图片：

---
import { Image } from 'astro:assets'
---

<Image 
  src="https://example.com/image.jpg" 
  alt="External image" 
  width={800}
  height={600}
/>

规则：

始终指定 width 和 height 以预防 CLS (布局偏移)
对首屏下方的图片使用 loading="lazy"
优先使用 webp 或 avif 格式
确保 Hero 图片经过优化且尺寸合适

SEO 模式

---
// src/components/SEO.astro
export interface Props {
  title: string
  description: string
  image?: string
  article?: boolean
  publishedTime?: Date
  author?: string
  tags?: string[]
}

const { 
  title, 
  description, 
  image = '/og-default.png',
  article = false,
  publishedTime,
  author,
  tags = []
} = Astro.props

const canonicalURL = new URL(Astro.url.pathname, Astro.site)
const imageURL = new URL(image, Astro.site)
---

<!-- 主要 Meta 标签 -->
<title>{title}</title>
<meta name="title" content={title} />
<meta name="description" content={description} />
<link rel="canonical" href={canonicalURL} />

<!-- Open Graph -->
<meta property="og:type" content={article ? 'article' : 'website'} />
<meta property="og:url" content={canonicalURL} />
<meta property="og:title" content={title} />
<meta property="og:description" content={description} />
<meta property="og:image" content={imageURL} />

asolis87/complementary-food-app

complementary-food-app 是什么？

在你喜欢的 AI 中提问

文档

何时使用

关键规则

决策标准：Astro vs Vue

项目结构（Screaming Architecture）

Astro 组件模式

布局模式

Content Collection 模式

Islands 架构 (Vue 组件)

客户端指令决策树

图片优化

SEO 模式

相关技能

steipete/sag

steipete/oracle

steipete/peekaboo

mattpocock/design-an-interface

mattpocock/prototype

mattpocock/grill-me