1. 标记示例文章为草稿#

用 VSCode 打开本地项目，手动将在 src/content/posts 目录下的所有示例文章文件中元数据里的 draft: false 改为 draft: true。

接着在项目目录下运行：

1
git add .
2
git commit -m "chore: 标记自带的文章为草稿"

2. 撰写文章#

注意到项目目录下的 package.json 文件里有可执行的脚本：

1
  "scripts": {
2
    "new-post": "node scripts/new-post.js"
3
  }

打开 scripts/new-post.js 文件，研究代码后知道：它接收文件名参数，并在 src/content/posts 目录下生成仅包含元数据模板的文章文件。

在项目目录下运行：

1
pnpm run new-post astro-firefly-blog-deploy/part1.md

这将在 src/content/posts 目录下创建子目录 astro-firefly-blog-deploy，并在该子目录下创建文章文件 part1.md。这文章文件包含着初始元数据模板：

1
---
2
title: part1.md
3
published: 2025-10-30
4
description: ''
5
image: ''
6
tags: []
7
category: ''
8
draft: false
9
lang: ''
10
---

通过 URL 路径 /posts/astro-firefly-blog-deploy/part1 访问到该文章。

为了避免使用嵌套过多的 URL 子路径，添加 slug: astro-firefly-blog-deploy-part1 到元数据块里。这样，可以通过 URL 路径 /posts/astro-firefly-blog-deploy-part1 访问到该文章。

3. 发布文章#

修改元数据，并撰写文章主体后，就可以将文章发布出去了。

在项目目录下运行：

1
git add .
2
git commit -m "feat: 添加文章 '基于 Firefly 主题的 Astro 博客部署（一）：从零到 GitHub Pages'"
3
git push origin custom

页面文件#

src/pages 目录下的文件（支持 .astro、.ts 等格式）会被 Astro 自动识别为页面。

下面展示了项目 src/pages 目录的实际结构，其中的每一个文件都对应一个或多个页面：

1
src/pages/
2
├── 404.astro
3
├── [...page].astro
4
├── about.astro
5
├── anime.astro
6
├── archive.astro
7
├── friends.astro
8
├── og/
9
│   └── [...slug].png.ts
10
├── posts/
11
│   └── [...slug].astro
12
├── robots.txt.ts
13
├── rss.astro
14
└── rss.xml.ts

静态路由#

Astro 使用基于文件的路由，根据项目 src/pages 目录下的文件结构来构建链接，自动将它们作为网站页面。

这意味着，虽然 Astro 项目没有单独的路由配置，但依然可以通过页面文件在 src/pages 目录中的路径推断出最终生成的路由。例如：

1
mysite.com/about -> src/pages/about.astro
2
mysite.com/404   -> src/pages/404.astro

注：像 [...slug].astro 这样采用特殊命名的页面文件属于动态路由，不属于静态路由的范畴。

组件脚本#

以 .astro 为后缀的文件是 Astro 组件，每个 Astro 组件由组件脚本和组件模板两部分组成。

Astro 使用代码围栏 --- 来识别组件脚本部分。虽然这种语法形式与 Front Matter 相似，但是两者作用不同：组件脚本内编写的是 TypeScript 代码，而非元数据。

后续会提到组件脚本中的一些作用和组件模板的一些语法。

动态路由#

类似 [...slug].astro 这样文件名中包含方括号的 Astro 组件用于实现动态路由。这类文件根据传入的动态参数，将文件名内方括号对应的部分替换为具体的参数值，生成对应的多个路由和匹配页面。

例如，对于 src/pages/posts/[category]/[post].astro 文件，当传入参数 { category: 'demo', post: 'hello-world' } 时，将会生成如下路由：

1
mysite.com/pages/posts/demo/hello-world -> src/pages/posts/[category]/[post].astro

剩余参数（例如：[...slug]）可以匹配任何深度的文件路径。

项目中 src/pages/posts 目录下的 [...slug].astro 文件，自然地令人联想到文章页面的生成和路由跟这页面文件有关，且动态路由参数的值与 slug 的值有关。

在静态站点生成模式下，因为必须在构建时确定所有路由。所以，在组件的脚本部分中，需要通过导出 getStaticPaths() 函数来指定所有可能的参数组合。该函数返回一个对象数组，其中每个对象的 param 字段定义了 slug 参数的具体取值。

1
// ...
2
export async function getStaticPaths() {
3
  const blogEntries = await getSortedPosts();
4
  return blogEntries.map((entry) => ({
5
    params: { slug: entry.slug },
6
    props: { entry },
7
  }));
8
}
9
// ...

这代码片段对应了之前提到的：

• 通过修改文章元数据里的 slug 字段值，能够更改文章的访问路径
• 组件脚本的作用之一是通过导出特定函数，向框架提供所需信息

内容集合#

根据前面的分析，文章内容存储在 src/pages 目录之外，这意味着默认情况下不会为内容生成页面和路由。文章页面的生成好像跟 src/content/posts 目录无关。那么，Astro 是如何定位文章文件、并为每篇文章生成对应的页面和路由的呢？

答案是通过内容集合。通过将 src/content/posts 目录定义为内容集合，让 Astro 统一管理其中的内容，每篇博客文章都作为该集合中的一个条目。

Astro 会自动扫描 src/content 目录下的所有子目录，将每个子目录识别为一个独立的内容集合。通过在 src/content 目录下添加 config.ts 文件，可以定义 Schema 来规范集合中内容的 Front Matter 或条目数据，这些 Schema 会通过 Zod 进行数据验证，确保数据格式的一致性。

项目中 src/content/config.ts 文件内容如下：

1
import { defineCollection, z } from "astro:content";
2

3
const postsCollection = defineCollection({
4
  schema: z.object({
5
    title: z.string(),
6
    published: z.date(),
7
    updated: z.date().optional(),
8
    draft: z.boolean().optional().default(false),
9
    description: z.string().optional().default(""),
10
    image: z.string().optional().default(""),
11
    tags: z.array(z.string()).optional().default([]),
12
    category: z.string().optional().nullable().default(""),
13
    lang: z.string().optional().default(""),
14
    pinned: z.boolean().optional().default(false),
15
    author: z.string().optional().default(""),
16
    sourceLink: z.string().optional().default(""),
17
    licenseName: z.string().optional().default(""),
18
    licenseUrl: z.string().optional().default(""),
19

20
    /* Page encryption fields */
21
    encrypted: z.boolean().optional().default(false),
22
    password: z.string().optional().default(""),
23

24
    series: z.string().optional(),
25

26
    /* For internal use */
27
    prevTitle: z.string().default(""),
28
    prevSlug: z.string().default(""),
29
    nextTitle: z.string().default(""),
30
    nextSlug: z.string().default(""),
31
  }),
32
});
33
const specCollection = defineCollection({
34
  schema: z.object({}),
35
});
36
export const collections = {
37
  posts: postsCollection,
38
  spec: specCollection,
39
};

Astro 提供了辅助函数 getCollection()，用于获取指定集合的全部内容，并以数组形式返回所有条目。

在 src/pages/posts/[...slug].astro 文件中，通过调用了 getSortedPosts() 函数间接使用了 getCollection() 函数，最终获得了经过排序的博客文章数组。

以下是第一篇博客文章的条目结构：

1
{
2
  id: 'astro-firefly-blog-deploy/part1.md',
3
  data: {
4
    title: '基于 Firefly 主题的 Astro 博客部署（一）：从零到 GitHub Pages',
5
    published: 2025-10-29T00:00:00.000Z,
6
    draft: false,
7
    description: '记录了自己是如何使用开源的 Firefly 主题，在 GitHub Pages 上从零开始部署基于 Astro 的个人博客。',
8
    image: '',
9
    tags: [
10
      '博客部署',
11
      'Astro',
12
      'Firefly',
13
      '开源主题',
14
      'GitHub Pages',
15
      'GitHub Actions',
16
      'Git'
17
    ],
18
    category: '实操记录',
19
    lang: '',
20
    pinned: false,
21
    author: '',
22
    sourceLink: '',
23
    licenseName: '',
24
    licenseUrl: '',
25
    encrypted: false,
26
    password: '',
27
    prevTitle: '',
28
    prevSlug: '',
29
    nextTitle: '',
30
    nextSlug: ''
31
  },
32
  body: '## 前言\r\n' +
33
    '\r\n' +
34
    '...',
35
  filePath: 'src/content/posts/astro-firefly-blog-deploy/part1.md',
36
  digest: '474c5b5ac94b1108',
37
  rendered: {
38
    html: '<section><h2 id="前言">前言<a class="anchor" href="#前言">....',
39
    metadata: {
40
      headings: [Array],
41
      localImagePaths: [],
42
      remoteImagePaths: [],
43
      frontmatter: [Object],
44
      imagePaths: []
45
    }
46
  },
47
  collection: 'posts',
48
  slug: 'astro-firefly-blog-deploy-part1',
49
  render: [Function: render]
50
}

观察上面的条目可以发现，虽然文章文件路径为 src/content/posts/astro-firefly-blog-deploy/part1.md，但其 slug 字段的值为 astro-firefly-blog-deploy-part1。值得注意的是，尽管在 src/content/config.ts 文件中的 Scheme 中并未定义 slug 字段，但仍然成功获取到了文章 Front Matter 中设置的 slug 值。

由于 slug 字段与 data 字段处于同一层级，猜测 Astro 会自动提取 Front Matter 中的 slug 字段值。这点可以通过检查其他未设置 slug 值的文章条目，观察其行为差异来验证。

在动态路由的实现中，通过在组件脚本中导出 getStaticPaths() 函数，其中该函数返回包含 params 字段的对象数组，每个 params 对象都包含一个 slug 字段。这意味着，通过修改文章 Front Matter 中的 slug 值，能够控制文章最终生成的访问路径。

NOTE

在撰写本文章的时候，虽然 Firefly 主题使用的 Astro 版本是 5.15.3，但是它使用的内容集合 API 是旧版的。Astro 5 引入了内容层 API 用于替代旧的版本 API。例如，在 Astro 5 中，要定义集合，必须在项目中创建 src/content.config.ts 文件，且在使用 defineCollection() 函数的时候必须配置 loader 用于加载数据源。再比如，渲染方法 entry.render() 被 render(entry) 函数取代。如果在项目里 src/content/config.ts 文件中强行添加 loader: glob({ ... })，也就启用了 Astro 5 的新内容层 API，这导致项目里 entry.render() 调用失败。

变量注入#

根据前面的分析，文章条目对象的 data 字段中存储着文章元数据。

组件脚本的另一个重要作用是创建可在模板中使用的变量。这些变量通过 Astro 的组件模板语法在组件模板中被引用。

具体实现的过程如下：将文章条目对象通过 getStaticPaths() 函数返回对象的 props 字段传入后，可以在组件脚本里通过 Astro.props 获取该对象，并基于其声明变量。随后，可以使用类似 JSX 语法在组件模板中使用。

通过在组件模板中使用组件脚本中定义的数据和值，最终生成动态创建的 HTML：

1
// ...
2
export async function getStaticPaths() {
3
  const blogEntries = await getSortedPosts();
4
  return blogEntries.map((entry) => ({
5
    params: { slug: entry.slug },
6
    props: { entry },
7
  }));
8
}
9

10
const { entry } = Astro.props;
11
// ...
12

13
---
14
<MainGridLayout
15
  banner={entry.data.image}
16
  title={entry.data.title}
17
  description={entry.data.description}
18
  lang={entry.data.lang}
19
  setOGTypeArticle={true}
20
  postSlug={entry.slug}
21
  headings={headings}
22
>
23
<!-- ... -->
24
</MainGridLayout>