用 Hexo + Redefine 搭建本站的全过程记录

前言

本站基于 Hexo 8 + Redefine 主题 搭建，托管在 Cloudflare Pages 上，全程纯静态、零运维。这篇文章记录完整搭建过程，也作为后续环境配置类文章的模板示例。

环境准备

硬性要求：Node.js ≥ 20.19.0（Hexo 8 的 engines 要求）。

node -v   # v24.11.1
npm -v    # 11.6.2
git --version

项目初始化

hexo init 无法在非空目录执行，因此采用「临时目录初始化 + 拷贝合并」的三步方案：

# 1. 在外层建临时空目录并初始化（跳过自动安装，稍后统一装）
npx --yes hexo init hexo_tmp --no-install

# 2. 全量拷贝进项目目录（docs/PRD.md 不会被覆盖）
cp -a hexo_tmp/. my_blog/ && rm -rf hexo_tmp

# 3. 在项目目录安装依赖
npm install

安装主题与功能插件

npm install hexo-theme-redefine \
  hexo-generator-searchdb hexo-generator-sitemap \
  hexo-generator-feed hexo-wordcount hexo-cli -D

然后在站点 _config.yml 里启用主题：

theme: redefine

覆盖式主题配置（核心规则）

Redefine 的所有自定义只写根目录 _config.redefine.yml，不改动主题源文件，这样主题升级不会丢失配置。几个关键段落：

# 主题色：青绿 + 暖金
colors:
  primary: "#14b8a6"
  secondary: "#f59e0b"

# 导航栏（图标是 FontAwesome 6 类名）
navbar:
  links:
    首页:
      path: /
      icon: fa-solid fa-house

# 首页横幅 + 打字机副标题
home_banner:
  image:
    light: /img/top_img.svg
    dark: /img/top_img.svg
  subtitle:
    text:
      - 技术为主，生活为辅

# 本地搜索（数据源由 hexo-generator-searchdb 生成 search.xml）
navbar:
  search:
    enable: true

# 访问统计：vercount，不蒜子的兼容替代，免注册
global:
  website_counter:
    enable: true

一个深合并陷阱：_config.redefine.yml 与主题默认值是深度合并——默认存在的键不会被「留空」删除。比如默认导航自带 Home 项，想隐藏它必须显式覆盖为 path: none，否则导航栏会出现两个「首页」。

页面模板：数据与页面分离

Redefine 的友链、相册、工具书签页都用「页面声明 + 数据文件」的模式，数据放 source/_data/：

页面	页面 front-matter	数据文件
标签	`template: tags`	无需数据
分类	`template: categories`	无需数据
友链	`template: links`	`_data/links.yml`
相册	`template: masonry`	`_data/masonry.yml`（瀑布流，建议写 width/height）
工具书签	`type: bookmarks`	`_data/bookmarks.yml`（左侧分类锚点自动生成）

以友链为例，source/link/index.md 只需：

---
title: 友链
template: links
---

友链数据写在 source/_data/links.yml：

- links_category: 框架与主题
  has_thumbnail: false
  list:
    - name: Hexo
      link: https://hexo.io/
      avatar: /img/links/hexo.png
      description: 快速简洁的静态博客框架

404 页不用做——主题内置 generator 自动产出 404.html。

自定义样式与特效注入

主题没有开关的样式细节走 inject 注入。两个实战经验：

加载顺序：inject.head 注入的 CSS 排在主题样式之前，覆盖主题同名规则必须加 !important（比如关闭横幅容器的 will-change: transform，否则 GPU 合成层会让标题文字抗锯齿退化、看起来发虚）。
swup 防重入：Redefine 的无刷新换页（swup）会重新执行注入脚本，特效脚本直接注入会在每次换页后叠加执行——粒子越来越密、监听器重复绑定。要用 window 标志位包一层「只初始化一次」的加载器。

inject:
  enable: true
  head:
    - '<link rel="stylesheet" href="/css/custom.css">'
  footer:
    - '<script src="/js/click-ripple.js"></script>'

部署到 Cloudflare Pages

推送到 GitHub 后，在 Cloudflare Pages 关联仓库即可自动构建：

构建命令：npx hexo generate
输出目录：public
环境变量：NODE_VERSION=24

问题排查

hexo init 报目录非空：按上面的三步方案处理。
改了 _config.redefine.yml 预览不生效：hexo server 不监听主题覆盖配置，Ctrl+C 重启 npx hexo server；提示端口占用就换 -p 4001，或 netstat -ano | findstr :4000 找到 PID 后 taskkill /F /PID 清掉残留进程。
代码块没有颜色：站点配置 syntax_highlighter 的注册名是 highlight.js（带 .js），写成 highlight 会导致高亮整体失效。
外部图片裂图：结构小图（favicon、友链头像）一律下载入库放 source/img/，外链不可控。

总结

整体流程：初始化 → 主题与插件 → _config.redefine.yml 覆盖配置 → 页面模板与数据文件 → 特效注入 → 推送自动部署。规范先行（本文对应 docs/PRD.md），后续迭代按 PRD 版本记录滚动更新。

后记：本站最初用 Butterfly 搭建，2026-09-06 迁移到 Redefine，本文已同步改写为现行技术栈。

weary's Blog