博客重启记

发表于 分类于 本文字数： 2.8k 阅读时长 ≈ 3 分钟

时隔五年，把这个博客重新捡起来了。上一篇更新停在 2021 年 9 月，那时候是刚搭好博客发的搭建教程，此后就再没写过一个字。

本地的 Hexo 源码在几次换电脑之后早就丢了，GitHub 上的仓库里只剩下 2021 年 hexo deploy 推上来的构建产物——一堆 HTML/CSS/JS，没有一行 Markdown。想续写，等于要从”考古现场”重启。

这篇记录一下重启的过程，也算给未来的自己留一个”再丢一次源码也能救回来”的说明书。

起点：只剩产物，没有源码

翻开仓库，看到的是这样一片废墟：

1
2
3
4
5
6
7
winchey.github.io/
├── 2021/09/13/基于Hexo.../index.html
├── archives/  categories/  tags/
├── css/  js/  images/
├── index.html
├── search.xml
└── CNAME

全是 Hexo 生成的静态文件。Hexo 默认的部署方式 hexo deploy 只推 public/ 目录，Markdown 源文件、_config.yml、主题配置这些”真正的博客”从头到尾没进过 Git。本地一丢，源码就真丢了。

这个坑其实挺常见——Hexo 官方文档没有把”源码也要用 Git 管起来”当作必须项来强调，很多人第一次搭博客就是照默认流程走，直到某天换电脑才发现自己一直在裸奔。

决策：换栈，还是原地重建

一开始想过换 Typecho：PHP 动态 CMS，网页后台直接写、直接发，不用命令行部署。但仔细算了一下代价：

  • 得买 VPS，一年 60~300 块起
  • 域名在国内服务器要备案，境外服务器又慢
  • 定期升级 PHP、防爆破、备份数据库
  • 数据锁在数据库里，将来想换回静态又麻烦

对于一个”几年才写一次”的博客来说，静态方案是唯一合理选择。Typecho 是好东西，但不是给我这种写作频率的人用的。

最后决定原地重建 Hexo，但这次把架构改对：

  • Markdown 源码进 Git 版本管理
  • 部署交给 GitHub Actions 自动化
  • 换电脑后 git clone 就能继续写

新架构：源码/产物分离

1
2
3
4
5
6
winchey.github.io 仓库
├── main 分支          ← Hexo 源码（.md、_config.yml、themes、workflow）
├── gh-pages 分支      ← 构建产物 HTML（Actions 生成，不用管）
└── legacy-build 分支  ← 2021 年的老 HTML 备份（安全网）

写文章 → git push origin main → GitHub Actions 自动构建 → 推到 gh-pages → 网站更新

之后的写作流程只有三步：

1
2
3
npx hexo new "文章标题"
# 用 Typora / VSCode 写 Markdown
git add . && git commit -m "post: 标题" && git push

推完两三分钟，www.liwanqing.com 自动更新。没有命令行部署，没有手动 build，没有 SSH 到服务器。

迁移过程中踩到的几个坑

1. hexo init . 不能在非空目录里跑

Hexo 会把 .git 目录也算成”非空”，直接拒绝初始化。绕过办法是先在临时目录初始化：

1
2
hexo init /tmp/hexo-init
cp -R /tmp/hexo-init/. .   # 拷回，保留 .git

2. _config.yml 改动不热重载

hexo server 只监听 source/ 目录的变化。改 _config.yml 或 _config.next.yml 必须重启服务才能看到效果。改一次配置刷不出来别慌，重启就好。

3. theme: next 在 GitHub Pages 上会触发一次莫名其妙的 Jekyll 报错

第一次 push 之后，Actions 页面除了我们的 Hexo workflow，还多了一个 GitHub Pages 默认触发的 Jekyll 构建任务，报错 The next theme could not be found。

原因是 Pages Source 默认从 main 分支跑 Jekyll，Jekyll 看到 theme: next 以为要找一个叫 “next” 的 Jekyll Ruby gem 主题（其实这是 Hexo 主题名）。

解法很简单——把 Pages Source 从 main 切到 gh-pages 分支就好。切完之后，Jekyll 那个”僵尸构建”就再也不会跑了。

4. NexT 8.x 的 back-to-top 按钮跟侧边栏同侧

Pisces 布局的侧边栏在左，回顶按钮就跟着放到了左下角，不习惯。用 custom_file_path.style 挂一个自定义 stylus 覆盖：

1
2
3
.back-to-top
  left: auto !important
  right: 30px !important

5. NexT 侧边栏”链接”想改成”友链”

主题的区块标题在 i18n 文件里，改 node_modules 里的 yml 文件太丑——npm 更新就没了。用 Hexo 的 after_render:html 过滤器优雅地替换：

1
2
3
4
5
6
7
// scripts/rename-links-title.js
hexo.extend.filter.register('after_render:html', function (str) {
  return str.replace(
    /<div class="links-of-blogroll-title">([\s\S]*?)链接\s*<\/div>/g,
    '<div class="links-of-blogroll-title">$1友链</div>'
  );
});

Hexo 会自动加载 scripts/ 目录下的所有脚本，这种小改造走这条路最干净。

老文章的迁移

原本以为要写脚本把老 HTML 反向转成 Markdown，翻了下 search.xml 发现只有两篇——一篇 Hexo 自带的 hello-world 示例（直接扔掉），一篇 2021 年写的搭建教程。

手工把那一篇的正文转成 Markdown，加上 front-matter，图片路径改成 /images/... 的绝对路径。永久链接保持 :year/:month/:day/:title/ 不变，所以老链接可以无缝访问。

现在拥有了什么

一个不会再丢源码的博客工程。一个每次 push 自动构建部署的流水线。一个 legacy-build 备份分支作为安全网。

以及最重要的：一个终于可以继续写下去的地方。

再见 2021 年的自己。这里从今天起重新开始。

后记

本次博客重启从零到上线的全过程——环境搭建、架构决策、迁移脚本、样式调优、GitHub Actions 配置、踩坑排查——全权由大模型 Claude Opus 4.7 (1M context) 协作完成。我负责提需求、审美取舍和最终决定，剩下的动手活儿都交给了它。

包括这篇文章的初稿。