Astro 学习总结：核心知识体系回顾

---
// src/components/SongCard.astro：组件三段式，frontmatter 写构建期逻辑
interface Props {
  title: string // 歌曲名
  singer: string // 演唱歌姬
  themeColor: string // 粉丝团应援色
}
const { title, singer, themeColor } = Astro.props
---
<article style={`border-left: 4px solid ${themeColor}`}>
  <h3>{title}</h3>
  <p>演唱：{singer}</p>
</article>

---
// src/pages/singers/[id].astro：动态路由，构建期枚举全部歌姬主页
interface Singer {
  id: string
  name: string
}

export async function getStaticPaths() {
  const singers: Singer[] = await fetch('https://api.fandex.dev/singers').then(
    (r) => r.json(),
  )
  return singers.map((s) => ({ params: { id: s.id } }))
}

const { id } = Astro.params
---
<h1>歌姬主页：{id}</h1>
<a href="/singers/">返回歌姬列表</a>

// src/content.config.ts：为歌曲评测文档定义"借书卡"
import { defineCollection } from 'astro:content'
import { z } from 'astro/zod'
import { glob } from 'astro/loaders'

const songs = defineCollection({
  loader: glob({ pattern: '**/*.md', base: './src/content/songs' }),
  schema: z.object({
    title: z.string(), // 歌曲名
    singer: z.string(), // 演唱歌姬
    producer: z.string(), // P 主
    themeColor: z.string(), // 应援色
    publishedAt: z.coerce.date(), // 发布日期，自动转换字符串
  }),
})

export const collections = { songs }

---
// src/pages/songs/index.astro：查询歌曲评测并按发布日期倒序
import { getCollection } from 'astro:content'

const songs = (await getCollection('songs')).sort(
  (a, b) => b.data.publishedAt.valueOf() - a.data.publishedAt.valueOf(),
)
---
<h1>歌曲评测库</h1>
<ul>
  {songs.map((song) => (
    <li>
      <a href={`/songs/${song.id}/`}>{song.data.title}</a>
      <span>应援色：{song.data.themeColor}</span>
    </li>
  ))}
</ul>

---
// src/pages/index.astro：整页静态，仅投票按钮是需要水合的岛屿
import VoteButton from '../components/VoteButton.tsx'
---
<h1>本季歌姬人气投票</h1>
<p>页面其余部分不携带任何 JavaScript。</p>
<!-- client:visible：进入视口才加载并水合，首屏成本趋近于零 -->
<VoteButton client:visible singer="初霜" />

// astro.config.mjs：注册 React 集成，让 .tsx 岛屿可用
import { defineConfig } from 'astro/config'
import react from '@astrojs/react'

export default defineConfig({
  integrations: [react()],
  site: 'https://fandex.example.com', // 供 sitemap 与 canonical 使用
})

// src/actions/index.ts：粉丝团报名的服务端校验
import { defineAction } from 'astro:actions'
import { z } from 'astro/zod'

export const server = {
  fanClub: {
    join: defineAction({
      input: z.object({
        nickname: z.string().min(1, '昵称不能为空'),
      }),
      handler: async (input) => {
        // 通过校验后才会执行，这里可以安全地写入数据库
        return { welcome: `欢迎加入粉丝团，${input.nickname}` }
      },
    }),
  },
}

---
import VoteButton from '../components/VoteButton.tsx'
---
<!-- 错误：按钮只是 HTML 照片，点击毫无反应 -->
<VoteButton singer="初霜" />

<!-- 修正：加上 client 指令，组件才会水合成活岛屿 -->
<VoteButton client:load singer="初霜" />

---
import Player from '../components/Player.tsx'
import BackTop from '../components/BackTop.tsx'
---
<!-- 错误：两个组件首屏就加载运行时，零 JS 优势被吃掉 -->
<Player client:load song="星屑协奏曲" />
<BackTop client:load />

<!-- 修正：按交互时机选择指令，滚动可见或空闲时再水合 -->
<Player client:visible song="星屑协奏曲" />
<BackTop client:idle />

---
// 错误：frontmatter 在构建期执行，不存在 window 与 document
const width = window.innerWidth
---
<p>当前宽度：{width}</p>

<!-- 修正：把浏览器逻辑放进客户端岛屿组件 -->
---
import ViewportInfo from '../components/ViewportInfo.tsx'
---
<ViewportInfo client:idle />

---
// 错误：静态输出时 [id].astro 没有导出 getStaticPaths，构建直接报错
const { id } = Astro.params
---
<h1>歌姬 {id}</h1>

---
// 修正：枚举全部合法参数后再读取动态段
export async function getStaticPaths() {
  const singers = await fetch('https://api.fandex.dev/singers').then((r) => r.json())
  return singers.map((s: { id: string }) => ({ params: { id: s.id } }))
}
const { id } = Astro.params
---
<h1>歌姬 {id}</h1>

// 错误：frontmatter 里的日期是字符串，z.date() 校验直接失败
schema: z.object({
  publishedAt: z.date(),
})

// 修正：使用 z.coerce.date() 自动把字符串转成 Date
schema: z.object({
  publishedAt: z.coerce.date(),
})

---
import VoteButton from '../components/VoteButton.tsx'
---
<!-- 错误：Astro 模板没有事件系统，onClick 被原样输出成非法属性 -->
<button onClick={() => vote()}>投票</button>

<!-- 修正：交互交给岛屿组件，事件写在 .tsx 内部 -->
<VoteButton client:load singer="初霜" />

// 错误：未配置 base，链接指向域名根路径，部署后全部 404
export default defineConfig({})

// 修正：声明 base，让链接统一生成 /repo/ 前缀
export default defineConfig({ base: '/repo/' })