Astro 博客搭建全过程：从零到上线

这个博客一开始用的是 AstroPaper，后来换成了 Firefly。这篇按现在的搭法重新写了一遍，命令和路径都是我自己跑通过的。

搭完你会有一个这样的博客：

静态站点，构建完就是一堆 HTML，放哪都能跑
自带暗色模式、全文搜索、RSS、站点地图
文章用 Markdown 写，frontmatter 写错了构建时直接报错
可以部署到 Vercel、Cloudflare Pages，也可以自己用 Docker 跑

需要会一点命令行，Node.js 用过就行。

一、环境准备#

Firefly 基于 Astro 7，对版本要求比较新：

Node.js 22 或更高（准确地说是 22.23 以上）
pnpm 11 或更高，项目里有脚本强制只能用 pnpm 装依赖
Git

1
node -v      # 低于 v22 需要升级
2
pnpm -v      # 没装就 npm install -g pnpm
3
git --version

macOS 可以用 Homebrew 装 Node：

1
brew install node

编辑器推荐 VS Code，装上 Astro 官方扩展，.astro 文件才有高亮和提示。

二、创建项目#

Firefly 不走 pnpm create astro，直接克隆仓库。建议先在 GitHub 上 Fork 一份到自己账号下，再克隆自己的那份，以后部署和同步更新都方便：

1
git clone https://github.com/<你的用户名>/Firefly.git my-blog
2
cd my-blog
3
pnpm install
4
pnpm dev

打开 http://localhost:4321 就能看到演示站了。

Tip

pnpm install 会下载几个平台相关的二进制包，比如搜索用的 Pagefind，单个就有几十 MB。网络不稳的时候可能下了一半就断，pnpm 还会显示安装成功，等到 pnpm build 最后一步才报 Failed to install either of [pagefind_extended, pagefind]。遇到这种情况，删掉 node_modules 重装一次，或者换个网络环境再装。

三、项目结构#

只列出平时会动到的部分：

1
my-blog/
2
├── astro.config.mjs        # Astro 配置：插件、Markdown、sitemap 等
3
├── src/
4
│   ├── config/             # 站点配置，按功能拆成很多个文件
5
│   ├── content/
6
│   │   ├── posts/          # 文章
7
│   │   └── spec/           # 关于页、友链页、留言板的正文
8
│   ├── assets/images/      # 头像、壁纸等，构建时会自动压缩
9
│   └── layouts/            # 页面布局，加统计代码、站长验证在这里
10
└── public/                 # 原样复制的静态文件，favicon 放这里

Firefly 的配置没有塞进一个大文件，而是拆在 src/config/ 下，最常改的几个：

文件	管什么
`siteConfig.ts`	站点标题、域名、主题色、页面开关、文章列表样式
`profileConfig.ts`	侧边栏头像、昵称、简介、社交链接
`navBarConfig.ts`	顶部导航菜单
`backgroundWallpaper.ts`	首页横幅的壁纸、标题、副标题
`sidebarConfig.ts`	侧边栏放哪些小组件
`commentConfig.ts`	评论系统
`friendsConfig.ts`	友链列表

四、改成你自己的站#

站点信息#

打开 src/config/siteConfig.ts，至少改这几项：

1
export const siteConfig: SiteConfig = {
2
  title: "七号研习社",
3
  subtitle: "记录技术、生活与思考",
4
  site_url: "https://llxx.cc",
5
  description: "777 的个人博客，记录技术、生活与思考。",
6
  timezone: "Asia/Bangkok",
7
  // ...
8
};

site_url 一定要改成你的域名，RSS、sitemap 和分享卡片里的链接都靠它生成。

同一个文件顶部有个 pages 开关表，演示站开了一堆页面：动态、项目、相册、书签、打赏、追番等等。用不上的设成 false，对应的页面会返回 404，导航栏里的入口也会自动隐藏：

1
const pages = resolvePageToggles({
2
  friends: true,
3
  guestbook: false,
4
  dynamic: false,
5
  projects: false,
6
  gallery: false,
7
  booknav: false,
8
  sponsor: false,
9
  // ...
10
});

头像、图标和横幅#

头像：图片放到 src/assets/images/，在 profileConfig.ts 里改 avatar
网站图标：PNG 放到 public/favicon/，在 siteConfig.ts 的 favicon 里列出来。建议放一张 180×180 的，iPhone 添加到主屏幕时会用它
首页横幅：标题、副标题和下面那排图标链接都在 backgroundWallpaper.ts 的 homeText 里

演示站的横幅标题、社交链接、友链、关于页都是作者自己的内容，记得逐个换掉。偷懒的办法是全局搜一下 cuteleaf 和 xiaye，搜到的基本都要改。

评论#

commentConfig.ts 里的 type 默认是 "none"，即不开评论。支持 Twikoo、Waline、Giscus、Artalk、Disqus，想开哪个就把 type 改成对应的名字，再填好下面那一段配置。我这里没开。

五、写文章#

文章放在 src/content/posts/ 下，子目录会原样变成网址的一部分。我按年月放：

1
src/content/posts/
2
└── 2026/
3
    └── 11/
4
        ├── astro-blog-setup-guide.md
5
        └── img/
6
            └── screenshot.png

这篇文章的地址就是 /posts/2026/11/astro-blog-setup-guide/。图片放在旁边的 img/ 里，正文用相对路径 ![说明](./img/screenshot.png) 引用，构建时会自动转成 WebP。

frontmatter 长这样：

1
---
2
title: Hello World
3
published: 2026-11-04T12:00:00.000Z
4
description: 我的第一篇博客文章。
5
category: 技术
6
tags:
7
  - Astro
8
author: "777"
9
pinned: false
10
draft: false
11
---

几个字段说明：

category 只能填一个，tags 可以填多个。首页顶部的分类栏就是按 category 统计的
pinned: true 会把文章置顶
draft: true 是草稿，本地 pnpm dev 能看到，正式构建时会被排除
updated 填最后修改时间，超过一定天数文章底部会提示”上次编辑于……”

Warning

字段值是纯数字时要加引号。比如我的昵称是 777，写成 author: 777 会被 YAML 当成数字，构建直接报错，必须写 author: "777"。

也可以用脚本建文章，它会帮你生成 frontmatter：

1
pnpm new-post 2026/11/hello-world

六、Markdown 扩展#

除了标准 Markdown，Firefly 还多了几样常用的。

提醒块，用的是 GitHub 的写法：

1
> [!NOTE]
2
> 普通提示。
3

4
> [!WARNING]
5
> 需要注意的地方。

可选的还有 TIP、IMPORTANT、CAUTION。上面那两个黄框就是这么写出来的。

GitHub 仓库卡片，一行就能插入一个带 Star 数的卡片：

1
::github{repo="CuteLeaf/Firefly"}

代码块用的是 Expressive Code，自带复制按钮和语言标识，超过 15 行的代码默认折叠。代码块里要再嵌一个代码块时，外层改用 ~~~ 包起来就行：

1
```bash
2
echo "Hello from my blog!"
3
```

七、搜索、RSS 和 sitemap#

这三样 Firefly 都配好了，不用另外装：

搜索：Pagefind。pnpm build 的最后一步会扫描生成好的 HTML，在 dist/pagefind/ 里生成索引，搜索完全在浏览器里完成，不需要服务器
RSS / Atom：/rss.xml 和 /atom.xml
sitemap：/sitemap-index.xml。在 pages 里关掉的页面会自动排除，其他想排除的页面可以在 astro.config.mjs 的 sitemap({ filter }) 里加规则

八、加统计和站长验证#

Google Analytics、Umami、Microsoft Clarity 在 src/config/analyticsConfig.ts 里填 ID 就行。

不在列表里的代码，比如 Google AdSense 的站点验证，直接加到 src/layouts/Layout.astro 的 <head> 里：

1
<head>
2
  <meta charset="UTF-8" />
3
  <meta name="google-adsense-account" content="ca-pub-xxxxxxxxxxxxxxxx" />
4
  ...
5
</head>

九、部署上线#

先在本地完整构建一次，确认没有报错：

1
pnpm build     # 输出到 dist/
2
pnpm preview   # 在 localhost:4321 预览构建结果

方案一：Vercel / Netlify / Cloudflare Pages#

最省事。代码推到 GitHub，在平台上导入仓库，填两个命令：

安装命令：pnpm install
构建命令：pnpm build
输出目录：dist

之后每次 push 都会自动重新部署。Firefly 自带了 vercel.json，用 Vercel 的话连这几项都不用填。

方案二：Docker + Nginx#

有自己的服务器的话，用多阶段构建：

1
FROM node:lts AS base
2
WORKDIR /app
3
RUN corepack enable && corepack prepare pnpm@latest --activate
4

5
COPY package.json pnpm-lock.yaml ./
6
RUN pnpm install --frozen-lockfile
7

8
COPY . .
9
RUN pnpm run build
10

11
FROM nginx:mainline-alpine-slim
12
COPY --from=base /app/dist /usr/share/nginx/html
13
EXPOSE 80

1
docker build -t my-blog .
2
docker run -d -p 80:80 --restart unless-stopped my-blog

十、从 AstroPaper 迁移过来要注意什么#

如果你和我一样是从别的 Astro 主题换过来的，这几件事要留意：

frontmatter 字段名不一样。AstroPaper 的 pubDatetime、modDatetime、featured、ogImage，在 Firefly 里分别是 published、updated、pinned、image，另外多了一个 category。文章多的话写个小脚本批量替换，正文不要动
文章目录换了。从 src/data/blog/ 挪到 src/content/posts/，子目录结构保持不变的话，文章网址也不会变，搜索引擎收录和别人引用的链接都不会失效
演示内容很多。看板娘模型、音乐播放器、示例公告、作者自己的友链和打赏链接，都要手动关掉或删掉。光 public/pio/ 里的看板娘模型就有 15 MB，不用的话直接删
评论数据和路径绑定。Twikoo 这类评论系统按页面路径存评论，路径一变，旧评论就对不上了

日常写作流程#

搭好以后，平时写文章就是：

pnpm new-post 2026/11/文章名 新建文件
填好 frontmatter，写正文
pnpm dev 本地看效果
提交、push，等自动部署

搭博客本身花不了多少时间，花时间的是把演示站的东西一点点换成自己的，还有之后能不能坚持写下去。