从Hexo迁移到Astro部署记录

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

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

• 主题改不动：想加个新功能、调个布局，得翻模板源码加硬改样式，主题一升级就冲突，越改越不敢动；
• 构建越来越慢：文章一多，hexo generate 要跑好几分钟，改个错别字也要等半天；
• 国内打开不稳：GitHub Pages 直连时快时慢，图片偶尔加载失败；主题默认引的国外 CDN（jsdelivr、Google Fonts）经常卡住加载不出来——这个后面”字体本地化”和”Cloudflare 双部署”两章就是为了治它；
• 想换主流方案：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 CDN 下载 3 个在线字体（Zen Maru Gothic / Inter / JetBrains Mono）。最省事的做法是直接用在线字体——用 Fontsource + jsdelivr CDN 几行 CSS 就能引入，网络能访问 jsdelivr 时：

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");

然后在字体配置里直接引用对应字体名即可，不用下载文件、不用子集化。我一开始就是这么用的，当时网络能连上 jsdelivr。

但在线字体的机制是访客打开页面时由浏览器现场去 cdn.jsdelivr.net 拉取——大多数访客在国内，直连这个域名经常连不上，字体就加载不出来，页面回退成系统字体。所以为了访客体验，我需要找不连外网也能加载的方案，于是试了好几种方案：

最终做法：

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/6c55cf0b3694c8d5.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（换了思源黑体后更小），页面加载快了很多。

本站最终用的是这套本地化方案：字体文件存在站点自己的服务器上，访客打开本站不需要连任何外部字体服务，构建和线上都稳。

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

主题本身是二次元风格，加了几个装饰效果：樱花飘落、水波纹背景、卡片立体感。为了让它们可管理，我统一收敛到一个配置文件 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（公告分类），可以防止陌生人随意开新讨论刷屏。GitHub Discussions 的分类主要有这几个：

评论只需要展示和回复，用 Announcements 最合适：既能回复，又不怕陌生人随手开新帖。

七、友链页面#

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

1
friends: true,   // 原来是 false

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

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

友链的几种常见方式：

• 评论区申请：在友链页评论区留言，附上站点名、链接、简介、头像；
• 邮件申请：直接发邮件到站长邮箱，说明互换意愿和站点信息；
• 自助表单：友链页放一个登记表单，来访者填完自动收录，站长后台看提交记录。做法概括：① 找一个免费表单服务（如 Formspree、腾讯云开发静态网站托管自带表单能力）；② 复制它给的 action 地址，在友链页写一个简单的 HTML 表单（站点名/链接/简介/头像四个字段）；③ 提交后数据进表单服务后台，站长定期把新友链加进 friends.md 再构建发布；
• 先加后说：先在对方站点加上自己的链接，再通过评论/邮件告知对方回加。

本站用的是评论区 + 邮件：友链页底部有申请说明，评论里留下站点信息即可，详情见 src/content/spec/friends.md。

八、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. 创建 API Token#

在 Cloudflare 控制台右上角头像 → My Profile → API Tokens 页面，点右上角蓝色 Create Token 按钮：

然后选 Custom token，按下面的参数填：

• Token name：随便填，只是标签不影响功能（比如 blog-deploy、blog_deploy 都行）；
• Permissions：Account → Cloudflare Pages → Edit；
• Account resources：Include → 你的账号；
• 其他默认，点 Create 后复制 token（只显示一次）。

注意：token 相当于账号钥匙，不要提交到代码仓库。

以后想改 / 轮换 / 删除 token：Cloudflare 控制台 → 右上角头像 → My Profile → API Tokens，找到对应 token 后点右侧菜单：

• Edit：修改名称、权限、绑定的账号；
• Roll：轮换——生成一个新值，旧值立即失效（token 泄露或想换新时用这个）；
• Delete：彻底删除（部署不再需要时）。

token 只在创建时完整显示一次，Roll 之后记得把新值同步到 GitHub Secrets（见下文第 4 节）。

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 域名 + 每次部署的提交信息、状态、预览地址）：

4. 后续自动化：push 双平台同步#

目前 GitHub Pages 是 push 自动部署，Cloudflare Pages 是手动 wrangler pages deploy。想做到推一次代码、两个平台同时更新，在仓库新建 .github/workflows/deploy-cloudflare.yml，用官方 cloudflare/wrangler-action@v3：

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

展开收起

使用前提：把两个值配到 GitHub 仓库的 Secrets 里，步骤如下：

1. 打开 GitHub 仓库页：https://github.com/Lycaonide/lycaonide.github.io；
2. 点顶部 Settings 标签；
3. 左侧菜单 Security → Secrets and variables → Actions；
4. 点绿色的 New repository secret 按钮；
5. Name 填 CLOUDFLARE_API_TOKEN，Secret 填你的 Cloudflare API Token（创建方法见上文第 1 节），点 Add secret；
6. 再点一次 New repository secret：Name 填 CLOUDFLARE_ACCOUNT_ID，Secret 填 Cloudflare 账号 ID（控制台 URL 里 /xxx/ 那段），点 Add secret。

注意：Name 必须和 workflow 里引用的一致，不能随便起名——上图里填的就是 CLOUDFLARE_API_TOKEN（名字对不上，workflow 读不到，CF 部署会一直失败）。

配好之后，每次 git push 会自动构建并同时部署到 GitHub Pages 和 Cloudflare Pages。

十、总结#

这次迁移的核心经验：

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

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

1
git add -A
2
git commit -m "写点说明"
3
git push

1
$env:CLOUDFLARE_API_TOKEN = "你的token"
2
$env:CLOUDFLARE_ACCOUNT_ID = "9df1e93b29898adab711c0958d7bccec"
3
npx wrangler pages deploy dist --project-name my-firefly-blog --branch main