Astro 入门指南

┌─────────────────────────────────────────┐
│  Header (静态 HTML)                      │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────┐   文章内容                 │
│  │ 搜索组件  │   (静态 HTML/Markdown)    │
│  │ (交互岛) │                           │
│  └──────────┘                           │
│                                         │
│  ┌──────────────┐                       │
│  │   评论区      │                       │
│  │  (交互岛)    │                        │
│  └──────────────┘                       │
├─────────────────────────────────────────┤
│  Footer (静态 HTML)                      │
└─────────────────────────────────────────┘

---
// 同一个 Astro 页面中混用多个框架
import ReactCounter from '../components/ReactCounter.jsx'
import VueTimer from '../components/VueTimer.vue'
import SvelteForm from '../components/SvelteForm.svelte'
---

<main>
  <ReactCounter client:load />
  <VueTimer client:idle />
  <SvelteForm client:visible />
</main>

┌  astro  v5.1.0
│
◆  Where should we create your new project?
│  ./my-astro-blog
│
◆  How would you like to start your new project?
│  ● Use blog template (推荐初学者)
│  ○ Include sample files
│  ○ Empty
│
◆  Do you plan to write TypeScript?
│  ● Yes (推荐)
│  ○ No
│
◆  How strict should TypeScript be?
│  ● Strict (推荐)
│  ○ Strictest
│  ○ Relaxed
│
◆  Install dependencies?
│  ● Yes
│  ○ No
│
◆  Initialize a new git repository?
│  ● Yes
│  ○ No

my-astro-blog/
├── public/              # 静态资源（原样复制到输出目录）
│   └── favicon.svg
├── src/
│   ├── components/      # 组件目录
│   │   └── Card.astro
│   ├── content/         # 内容集合目录
│   │   └── blog/
│   │       └── first-post.md
│   ├── layouts/         # 布局组件
│   │   └── Layout.astro
│   ├── pages/           # 页面路由（文件即路由）
│   │   └── index.astro
│   ├── styles/          # 全局样式
│   └── content.config.ts # 内容集合配置
├── astro.config.mjs     # Astro 配置
├── package.json
└── tsconfig.json        # TypeScript 配置

---
// 这里是「组件脚本」(Frontmatter)
// 在服务端执行，不会发送到客户端
import Layout from '../layouts/Layout.astro'

const title = 'Hello Astro'
const items = ['苹果', '香蕉', '橙子']
---

<!-- 这里是「组件模板」 --><!-- 类似 JSX，但有一些差异 -->
<Layout title={title}>
  <h1>{title}</h1>
  <ul>
    {items.map((item) => <li>{item}</li>)}
  </ul>
</Layout>

<style>
  /* 组件样式（默认 scoped） */
  h1 {
    color: purple;
  }
</style>

---
// 1. 导入组件和模块
import Header from '../components/Header.astro'
import { formatDate } from '../utils/date'

// 2. 获取组件 Props
interface Props {
  title: string
  date: Date
}
const { title, date } = Astro.props

// 3. 获取 URL 参数
const { slug } = Astro.params

// 4. 请求外部数据（在构建时执行）
const response = await fetch('https://api.example.com/posts')
const posts = await response.json()

// 5. 定义局部变量
const formattedDate = formatDate(date)
const isProduction = import.meta.env.PROD
---

---
const name = 'Astro'
const isLoggedIn = true
const items = [1, 2, 3]
---

<!-- 变量插值 -->
<h1>Hello, {name}!</h1>

<!-- 条件渲染 -->
{isLoggedIn && <p>欢迎回来!</p>}
{isLoggedIn ? <Dashboard /> : <LoginForm />}

<!-- 列表渲染 -->
<ul>
  {items.map((item) => <li>Item {item}</li>)}
</ul>

<!-- 动态属性 -->
<div class={isLoggedIn ? 'user' : 'guest'}>
  <img src={`/avatars/${name}.png`} alt={name} />
</div>

<!-- 展开属性 -->
{/* 将对象所有属性展开为元素属性 */}
<Component {...props} />

---
// 不用写相对路径
import Header from '~/components/Header.astro'
import { SITE } from '~/config'

// 而不是
// import Header from '../../components/Header.astro'
---

blog/
├── plugins/              # Remark/Rehype 插件
├── public/               # 静态资源
├── scripts/              # 构建脚本
├── src/
│   ├── assets/           # 图片等资源
│   ├── components/       # UI 组件
│   │   ├── base/         # 基础组件 (Head, Footer, Link)
│   │   ├── backgrounds/  # 动画背景组件
│   │   ├── nav/          # 导航组件
│   │   ├── views/        # 视图组件 (渲染文章等)
│   │   └── widgets/      # 小部件 (返回顶部、返回等)
│   ├── content/          # 内容集合
│   │   ├── blog/         # 博客文章
│   │   ├── changelog/    # 更新日志
│   │   ├── projects/     # 项目数据
│   │   └── schema.ts     # Schema 定义
│   ├── layouts/          # 布局组件
│   ├── pages/            # 页面路由
│   ├── styles/           # 全局样式
│   ├── utils/            # 工具函数
│   ├── config.ts         # 站点配置
│   └── content.config.ts # 内容集合配置
├── astro.config.ts       # Astro 配置
├── uno.config.ts         # UnoCSS 配置
└── package.json

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "~/*": ["./src/*"]
    }
  }
}

---
// 无论文件在哪个层级，都可以这样导入
import { SITE } from '~/config'
import Header from '~/components/base/Header.astro'
import { formatDate } from '~/utils/date'
---