从零搭建一个 Hexo + Butterfly + GitHub Pages 博客，看着简单，实操下来还是踩了不少坑。这篇文章把过程中遇到的问题和解决方案整理出来，给同样在折腾的人一个参考。

环境准备

Node.js 和 Git 是前提，版本别太老就行：

1
2
3
node --version  # v18+
git --version   # 2.x+
npm --version

这一步基本不会出问题，跳过。

坑 1：Hexo 初始化目录必须为空

这是第一个低级错误。hexo init 要求目标目录是空文件夹，如果你提前建了目录并往里放了东西，init 会失败。

正确姿势：

1
2
3
mkdir my-blog
cd my-blog
hexo init .

或者让 Hexo 自己建目录：

1
2
3
hexo init my-blog
cd my-blog
npm install

坑 2：主题配置文件到底在哪改

Butterfly 主题安装完后，配置文件的加载优先级是这样的：

  1. _config.butterfly.yml（项目根目录，优先级最高）
  2. themes/butterfly/_config.yml（主题默认配置）
  3. _config.yml（Hexo 主配置，theme: butterfly 在这里改）

关键：不要直接改 themes/butterfly/_config.yml，不然以后升级主题你的修改全丢。正确做法是把需要改的配置写到项目根目录的 _config.butterfly.yml，它会覆盖主题默认值。

如果你没有这个文件，从主题目录拷一份出来改：

1
cp themes/butterfly/_config.yml _config.butterfly.yml

坑 3：插件要自己装

Butterfly 的很多功能只是前端展示，底层依赖的插件不会自动安装。开了什么功能，就要手动装对应的包：

功能 需要的包
字数统计 / 阅读时长 hexo-wordcount
站内搜索 hexo-generator-search + hexo-generator-searchdb
站点地图 hexo-generator-sitemap
一键部署 hexo-deployer-git

忘记装的结果就是经典报错 totalcount is not a function，排查半天发现少个包。

建议：改完配置后别急着 hexo g，先对着 Butterfly 文档确认一下有没有依赖遗漏。

坑 4：自定义 CSS 需要手动注入

在 source/css/ 下写了个 custom.css 以为会自动加载，结果死活不生效。Hexo 会把 source/ 下的文件拷贝到 public/，但不会自动加 <link> 标签。

需要在 _config.butterfly.yml 的 inject 部分手动声明：

1
2
3
inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">

坑 5：改完配置忘记 clean

改了 _config.yml 或 _config.butterfly.yml 之后，缓存不会自动刷新。如果不先 hexo clean 就直接 hexo g，改动的配置可能不生效。

安全流程：

1
2
hexo clean && hexo g && hexo s   # 预览
hexo clean && hexo g && hexo d   # 部署

坑 6：GitHub Pages 部署 403

HTTPS 方式推送需要 Personal Access Token。如果报 403，两个方案：

  • 方案 A（推荐）：改用 SSH 地址 git@github.com:An3035/An3035.github.io.git，一劳永逸
  • 方案 B：去 GitHub Settings → Developer settings → Tokens 生成一个带 repo 权限的 token，用它当密码

Windows 用户如果之前用 HTTPS 存过旧密码，去「控制面板 → 凭据管理器 → Windows 凭据」删掉 git:https://github.com 这个条目，否则会一直用旧密码反复失败。

坑 7：本地预览页面 404

hexo s 后访问 localhost:4000/about/ 或者某个文章报 404，通常两个原因：

  1. 那个页面根本不存在——检查 source/ 下有没有对应的 index.md
  2. 改了 _config.yml 里的 permalink 设置，但没 hexo clean 重新生成

折腾总结

Hexo 博客搭建的整体体验是：看文档觉得简单，实操全是细节。

但这套工具链成熟度很高，中文社区活跃，遇到问题基本都能搜到解决方案。花一两天踩完这些坑之后，后续写文章的体验就非常顺畅了——终端里敲三行命令，30 秒上线一篇。

如果你也刚开始折腾 Hexo，希望这篇能帮你少搜几次 Google。