F FisherHub Docs

01. 入门指南

Astro 是什么

Astro 是一个现代化的静态站点生成器（Static Site Generator, SSG），核心思路是在构建时尽可能输出纯静态 HTML，减少 JavaScript 的加载量。与传统框架（Next.js、Nuxt）不同，Astro 默认不做客户端水合（hydration），只有当组件标记为交互时才注入对应的 JS。

Astro 的三大设计原则：

  • 零 JS 默认 — 页面默认只输出 HTML + CSS，不发送任何 JS
  • Islands 架构 — 使用 Client Directives 精确控制哪些组件需要交互
  • 内容优先 — 原生支持 Markdown、MDX、Content Collections，适合文档站、博客等场景

项目初始化

使用 bun create astro 命令创建一个新项目：

bun create astro my-docs-site

安装过程中 Astro 会询问几个问题：

  1. 是否使用 TypeScript — 选 Yes
  2. 目录结构模板 — 选 Empty 或 Blog
  3. 是否安装依赖 — 选 Yes
  4. 是否初始化 Git 仓库 — 按需选择

项目创建完成后进入目录：

cd my-docs-site

如果需要手动安装 Astro（比如向现有项目添加），可以运行：

bun add astro

目录结构

一个典型的 Astro 项目结构如下：

my-docs-site/
├── public/                  # 静态资源（图片、字体、favicon）
├── src/
│   ├── components/          # Astro / 框架组件
│   ├── content/             # 内容集合（Markdown / MDX）
│   ├── layouts/             # 页面布局
│   ├── pages/               # 页面路由（文件即路由）
│   └── styles/              # 全局样式
├── astro.config.mjs         # Astro 配置文件
├── tsconfig.json            # TypeScript 配置
└── package.json

关键目录说明：

  • src/pages/ — 每个 .astro / .md / .mdx 文件自动对应一个路由
  • src/content/ — 通过 Content Collections 管理结构化内容
  • src/layouts/ — 布局组件，通过 YAML frontmatter 的 layout 字段引用
  • public/ — 该目录下的文件直接映射到站点根路径

文件路由基础

Astro 使用文件路由：src/pages/ 下的每个文件对应一个 URL 路径。

src/pages/
├── index.astro       → /
├── about.astro       → /about
├── blog/
│   ├── index.astro   → /blog
│   └── post-1.astro  → /blog/post-1
└── tags/[tag].astro  → /tags/:tag（动态路由）

一个简单的 Astro 页面组件：

---
// src/pages/index.astro
// 组件脚本区（运行在构建时）
const pageTitle = '首页'
---

<html lang="zh-CN">
  <head>
    <title>{pageTitle}</title>
    <meta name="viewport" content="width=device-width" />
  </head>
  <body>
    <h1>{pageTitle}</h1>
    <p>欢迎来到我的 Astro 站点</p>
  </body>
</html>

文件中的 --- 分隔符之间的部分是组件脚本，只在构建时执行。下方的 HTML 是组件模板，支持 JSX 表达式插值。

开发服务器

启动本地开发服务器：

bunx astro dev

默认端口是 4321，访问 http://localhost:4321 即可预览。

常用选项：

  • --port 指定端口，例如 --port 8125
  • --host 允许局域网访问，例如 --host 0.0.0.0

修改 src/pages/ 下的文件后，浏览器会自动热更新（HMR），无需手动刷新。

第一个页面

创建一个简单的页面，展示 Astro 模板语法的基本用法：

---
// src/pages/hello.astro
const now = new Date()
const sites = ['文档站', '博客', '门户']
---

<html lang="zh-CN">
  <head>
    <title>Hello Astro</title>
  </head>
  <body>
    <h1>Hello, Astro!</h1>
    <p>当前时间：{now.toLocaleString('zh-CN')}</p>
    <ul>
      {sites.map(site => <li>{site}</li>)}
    </ul>
  </body>
</html>

访问 http://localhost:4321/hello 即可看到效果。Astro 模板中可以用 {} 嵌入变量和表达式，支持 .map()、三元运算符等 JavaScript 语法。

下一步

熟悉了基础操作后，可以继续阅读下一章，了解 Content Collections 和路由系统。