从Hexo迁移到Astro部署记录

一、为什么从 Hexo 迁移到 Astro#

原来这个博客是用 Hexo 搭的（另一篇《学习用Hexo写博客》记录了完整过程），部署在 GitHub Pages 上，用起来没问题。但用久了有几个痛点：

• 主题老旧：Hexo 生态里好看的现代主题不多，定制麻烦；
• 性能一般：页面是整站生成，JS 和 CSS 越来越重；
• 想折腾：Astro 是当下内容站的主流方案，静态输出、组件化、生态活跃。

最终选型：

二、搭建项目与本地预览#

前置环境：需要 Node.js 20+（去 nodejs.org 下载安装）和 pnpm 包管理器：

1
# 安装 pnpm（Node.js 自带 corepack，也可用 npm 装）
2
npm install -g pnpm
3
pnpm --version   # 确认安装成功

Firefly 主题的仓库地址：CuteLeaf/Firefly。克隆后安装依赖：

1
# 克隆模板（我的目录是 my-firefly-blog）
2
git clone https://github.com/CuteLeaf/Firefly.git my-firefly-blog
3
cd my-firefly-blog
4

5
# 安装依赖并启动本地预览
6
pnpm install
7
pnpm dev

浏览器打开 http://localhost:4321 即可看到站点。之后每次改配置，本地跑 pnpm build + pnpm preview 验证，确认无误再推送。

三、双站并存：旧博客不丢#

迁移期间新站还没完全就绪，旧站不能直接关。方案是双站并存：

• 新站（Astro）：部署在 lycaonide.github.io 仓库，即主站 https://lycaonide.github.io；
• 旧站（Hexo）：保留原内容，作为项目页部署到 https://lycaonide.github.io/hexo-blog/。

等新站内容补齐后，再逐步把旧站文章迁过来，最后下线旧站即可。迁移过程零停服，随时可以回滚。

四、字体本地化（最大的坑：jsdelivr 被墙）#

这是迁移过程中最折腾的一环。主题默认从 jsdelivr CDN 下载 3 个在线字体（Zen Maru Gothic / Inter / JetBrains Mono），而 jsdelivr 在国内经常被墙，导致：

• 构建卡在字体下载、超时失败；
• 线上页面字体加载不出来，回退成默认字体，很丑。

试过的方案和结论：

最终做法：

1. 把 4 个 woff2 字体文件放进 public/assets/fonts/（字体可从主题自带的 assets 目录复制，或从 Google Fonts 下载对应字重的 woff2）；
2. 新建 src/styles/local-fonts.css，手写 @font-face：

1
@font-face {
2
  font-family: "Noto Sans SC";
3
  src: url("/_astro/fonts/2ae3372f6bc2f1d5.woff2") format("woff2");
4
  font-weight: 500;
5
  font-display: swap;
6
}
7
@font-face {
8
  font-family: "Space Grotesk";
9
  src: url("/_astro/fonts/6c826b4054a55260.woff2") format("woff2");
10
  font-weight: 500;
11
  font-display: swap;
12
}
13
@font-face {
14
  font-family: "JetBrains Mono";
15
  src: url("/_astro/fonts/0b2768d3228f0111.woff2") format("woff2");
16
  font-weight: 400;
17
  font-display: swap;
18
}
19
@font-face {
20
  font-family: "JetBrains Mono";
21
  src: url("/_astro/fonts/0a0e0606aec0d99b.woff2") format("woff2");
22
  font-weight: 700;
23
  font-display: swap;
24
}

3. fontConfig.ts 里把 selected 设为 ["system"]，让全局走系统字体；
4. 写一个子集化脚本：扫描构建产物里的所有 HTML，收集实际用到的字符，只保留这些字符生成轻量 woff2（核心代码用了 subset-font 库）：

1
// scripts/subset-fonts.ts（核心逻辑）
2
import subsetFont from "subset-font";
3
import { glob } from "glob";
4
import { readFile, writeFile } from "node:fs/promises";
5

6
// 1. 收集 dist/ 里所有 HTML 的实际字符
7
const htmlFiles = await glob(`${DIST_DIR}/**/*.html`);
8
const charSet = new Set<string>();
9
for (const file of htmlFiles) {
10
  const html = await readFile(file, "utf-8");
11
  for (const c of html.replace(/<[^>]+>/g, " ")) charSet.add(c);
12
}
13

14
// 2. 用 subset-font 生成子集 woff2，再替换 CSS/HTML 里的引用
15
const subset = await subsetFont(fontBuffer, [...charSet].join(""), {
16
  targetFormat: "woff2",
17
});
18
await writeFile(outFile, subset);

这个脚本已集成进 pnpm build（构建链会自动执行），也可以单独跑：npx tsx scripts/subset-fonts.ts。结果：字体体积从 3MB 压到约 140KB（换了思源黑体后更小），页面加载快了很多。

1
/* 放在全局样式入口文件顶部 */
2
@import url("https://cdn.jsdelivr.net/npm/@fontsource/zen-maru-gothic@5/index.css");
3
@import url("https://cdn.jsdelivr.net/npm/@fontsource/jetbrains-mono@5/index.css");
4
@import url("https://cdn.jsdelivr.net/npm/@fontsource/inter@5/index.css");

五、站点美化：装饰总开关#

主题本身是二次元风格，加了几个装饰效果：樱花飘落、水波纹背景、卡片立体感。为了让它们可管理，我统一收敛到一个配置文件 src/config/decorationConfig.ts：

1
export const decorationConfig = {
2
  sakura: true,   // 樱花飘落
3
  live2d: true,   // 看板娘
4
  waves: true,    // 背景水波纹
5
  card3d: true,   // 卡片立体感
6
};

想换”极简技术风”时，全部改成 false 就行，不用到处找开关。

六、评论系统：Giscus#

评论用的是 Giscus（基于 GitHub Discussions，免费、无广告、数据在自己仓库里）。接入步骤：

1. 开启 Discussions：仓库 Settings → Features → Discussions 勾选开启。开启后仓库导航栏会出现 Discussions 入口：

2. 安装 giscus App：giscus.app → Install，授权给博客仓库；
3. 生成配置：在 giscus 配置页填仓库名，页面会校验仓库状态（必须公开、已装 App、已开 Discussions），三项都满足会显示”成功”：

4. 写入主题配置 src/config/commentConfig.ts：

1
export const commentConfig = {
2
  type: "giscus",
3
  repo: "lycaonide/lycaonide.github.io",
4
  repoId: "R_kgDORApdOw",
5
  category: "Announcements",
6
  categoryId: "DIC_kwDORApdO84DFWdq",
7
  mapping: "title",        // 按文章标题匹配讨论
8
  reactionsEnabled: "1",
9
  inputPosition: "top",
10
  lang: "zh-CN",
11
  loading: "lazy",
12
};

补充：分类我选了 Announcements（公告分类），可以防止陌生人随意开新讨论刷屏。

七、友链页面#

主题自带了友链页，只是默认关闭。开启方法：

1
friends: true,   // 原来是 false

同时新建 src/content/spec/friends.md 写入友链说明（本站信息、申请方式、小要求），页面底部就会显示自定义的友链交换说明。

注意：友链内容页缺失会导致构建报错 friends page content not found，所以 开关和内容文件要一起建。

八、GitHub Actions 自动部署#

推送后自动构建发布，用的是 Actions workflow（.github/workflows/deploy.yml），这是本站实际在用的完整配置：

1
name: Deploy to GitHub Pages
2

3
on:
4
  push:
5
    branches: [ main, master ]
6
  workflow_dispatch:
7

8
# Pages 部署需要的权限
9
permissions:
10
  contents: read
11
  pages: write
12
  id-token: write
13

14
# 确保只有一个部署任务同时运行
15
concurrency:
16
  group: "pages"
17
  cancel-in-progress: false
18

19
jobs:
20
  build:
21
    runs-on: ubuntu-latest
22
    steps:
23
      - name: Checkout
24
        uses: actions/checkout@v4
25

26
      - name: Setup Node.js
27
        uses: actions/setup-node@v4
28
        with:
29
          node-version: '22'
30

31
      - name: Setup pnpm
32
        uses: pnpm/action-setup@v4
33
        with:
34
          version: 11.22.0
35
          run_install: false
36

37
      - name: Install dependencies
38
        run: pnpm install --no-frozen-lockfile
39

40
      - name: Build site
41
        run: pnpm run build
42

43
      - name: Create .nojekyll file
44
        run: touch dist/.nojekyll
45

46
      - name: Upload artifact
47
        uses: actions/upload-pages-artifact@v3
48
        with:
49
          path: dist  # Astro默认构建输出目录
50

51
  deploy:
52
    environment:
53
      name: github-pages
54
      url: ${{ steps.deployment.outputs.page_url }}
55
    runs-on: ubuntu-latest
56
    needs: build
57
    steps:
58
      - name: Deploy to GitHub Pages
59
        id: deployment
60
        uses: actions/deploy-pages@v4

几个关键点：

• touch dist/.nojekyll：GitHub Pages 默认用 Jekyll 处理，不建这个文件会把 _astro 这类目录忽略掉，页面会白屏；
• concurrency：防止多次 push 时部署任务互相打架；
• workflow_dispatch：想手动触发重新部署时，Actions 页面点一下即可。

每次 push 后，仓库的 Actions 页面会看到构建部署记录（绿色对勾表示成功，点进去能看每步日志）：

以后写文章只需要：

1
git add .
2
git commit -m "新文章"
3
git push

前置：git push 走 SSH，需要先在 GitHub 配置好 SSH 密钥（生成密钥、把公钥加到 GitHub → SSH and GPG keys，方法可参考本站《学习用Hexo写博客》一文第五节）。

等待 3-4 分钟，Actions 构建部署完成，线上自动更新，全程不用手动操作。

十、Cloudflare Pages 部署（国内访问加速）#

GitHub Pages 的服务器在境外，国内访问时快时慢，图片、字体偶尔要等很久。为了让国内访客更流畅，给本站加了一层 Cloudflare Pages 双部署：GitHub Pages 保持不变（原有链接不断），Cloudflare Pages 作为国内加速入口，两个域名内容同步。

双部署有什么用：

• 国内加速：Cloudflare 有全球 CDN（含国内优化节点），页面、图片、字体加载明显更快，这是最主要的价值；
• 双保险：一个平台出问题（GitHub 被墙、Pages 服务异常、DNS 污染），另一个域名随时能顶上，站点不”失联”；
• 评论/友链不受影响：Giscus 评论挂在 GitHub 仓库上、友链数据在配置里，两个域名共用同一套，换域名不丢数据。

两个网址内容完全一致，按网络环境任选：

• GitHub Pages：https://lycaonide.github.io
• Cloudflare Pages：https://my-firefly-blog.pages.dev

1
# 1. 构建（输出 dist/）
2
pnpm build
3

4
# 2. 配置凭据（PowerShell 用 $env: 前缀）
5
export CLOUDFLARE_API_TOKEN="你的API_TOKEN"      # 上一步创建的
6
export CLOUDFLARE_ACCOUNT_ID="你的账号ID"        # CF 控制台 URL 里 /xxx/ 那段
7

8
# 3. 创建 Pages 项目（仅首次）
9
npx wrangler pages project create my-firefly-blog --production-branch main
10

11
# 4. 部署 dist 目录
12
npx wrangler pages deploy dist --project-name my-firefly-blog --branch main

1
✨ Success! Uploaded 244 files (17.28 sec)
2

3
🌎 Deploying...
4
✨ Deployment complete! Take a peek over at https://ca824054.my-firefly-blog.pages.dev

3. 验证#

浏览器打开 https://my-firefly-blog.pages.dev，内容和 GitHub Pages 完全一致（同一个 dist 构建产物），国内访问明显更流畅：

Cloudflare 控制台的部署记录页（Production 域名 + 每次部署的提交信息、状态、预览地址）：

1
name: Deploy to Cloudflare Pages
2

3
on:
4
  push:
5
    branches: [main]
6
  workflow_dispatch:
7

8
jobs:
9
  deploy:
10
    runs-on: ubuntu-latest
11
    permissions:
12
      contents: read
13
    steps:
14
      - name: Checkout
15
        uses: actions/checkout@v4
16

17
      - name: Setup Node.js
18
        uses: actions/setup-node@v4
19
        with:
20
          node-version: '22'
21

22
      - name: Setup pnpm
23
        uses: pnpm/action-setup@v4
24
        with:
25
          version: 11.22.0
26
          run_install: false
27

28
      - name: Install dependencies
29
        run: pnpm install --no-frozen-lockfile
30

31
      - name: Build
32
        run: pnpm run build
33

34
      - name: Deploy to Cloudflare Pages
35
        uses: cloudflare/wrangler-action@v3
36
        with:
37
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
38
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
39
          command: pages deploy dist --project-name my-firefly-blog --branch main

十一、总结#

这次迁移的核心经验：

1. 配置收敛：装饰、评论、友链等开关集中在 config 文件里，方便统一管理；
2. 双站过渡：新旧站并存，内容迁完再下线，风险可控；
3. 自动化部署：GitHub Actions 让发布变成”push 就完事”。

最终效果就是你现在看到的这个站：Astro 7 + Firefly 主题 + GitHub Pages，樱花、评论、友链齐全，加载快还免费。