折腾了两天，我的 Hexo 博客终于上线了。从零到一，踩了不少坑，写篇文章记录一下。

为什么选 Hexo

需求很简单：静态博客、Markdown 写作、免费托管、能自定义主题。WordPress 太重，Notion 不够 geek，选了一圈最后锁定了 Hexo + GitHub Pages。Node.js 生态、中文社区活跃、Butterfly 主题颜值在线，够了。

环境配置，比想象的顺

Node.js 和 Git 都是现成的，三条命令就起跑了：

1
2
3
npm install -g hexo-cli
hexo init my-blog
cd my-blog && npm install

hexo s 跑起来，localhost:4000 看到默认页面的那一刻，还是有点小激动的。

主题选了 Butterfly

默认 Landscape 太素了，对比了几个热门主题后选了 Butterfly。好看，配置项多，中文文档完整。

1
npm install hexo-theme-butterfly --save

改 _config.yml 里一行：

1
theme: butterfly

然后从主题目录拷一份 _config.butterfly.yml 出来改。导航栏、头像、暗黑模式、侧边栏、字数统计，零零碎碎调了一下午。

踩坑记录

坑 1：totalcount is not a function

开启字数统计功能后报了这个错。原因很简单——忘了装 hexo-wordcount 插件。npm install 一下就解决了。Butterfly 很多功能只负责展示，底层依赖的插件要自己装。

坑 2：自定义 CSS 不生效

在 source/css/ 下写好了 custom.css，页面死活不加载。检查了半天发现要去 _config.butterfly.yml 的 inject.head 里手动注入：

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

Hexo 生成的时候才会把 source/ 下的文件原样拷到 public/，但 link 标签要自己加。

坑 3：部署权限

hexo d 往 GitHub 推送的时候报了 403。原因是用的 HTTPS 地址，需要 Personal Access Token 认证。后来切成了 SSH 地址就一劳永逸了：

1
2
3
4
deploy:
  type: git
  repo: git@github.com:An3035/An3035.github.io.git
  branch: main

前提是本地配过 SSH key 并加到 GitHub。

目前装了的插件

插件 用途
hexo-deployer-git 一键部署到 GitHub Pages
hexo-generator-search 站内搜索
hexo-generator-searchdb 搜索数据库
hexo-generator-sitemap SEO 站点地图
hexo-wordcount 文章字数 & 阅读时长
不蒜子（内置） 访问量统计

日常三件套

1
2
3
hexo new "文章标题"         # 新建文章
hexo s                     # 本地预览
hexo clean && hexo g && hexo d   # 上线部署

接下来

博客架子搭好了，接下来该认真写点东西了。计划先整理一下最近学的内容：AI 工具链、全栈项目笔记、一些踩坑记录。Flag 立在这里，督促自己保持更新频率。

第一天上线，就这样吧。如果你也在折腾 Hexo，希望这篇能帮你少走点弯路。