前言

这是 HEXO 开发笔记系列的最后一篇。前几篇从架构、视觉、功能、安全到搜索，完整介绍了 DoraTiger 主题的设计与实现。本篇收尾，聚焦工程化实践：CLI 命令、CDN 与本地资源管理、CI/CD 自动化、配置文档化，以及发布流程。

一、CLI 命令

1.1 设计原则

DoraTiger 的 CLI 命令遵循一个简单的原则 — 简化操作逻辑。参考了 factory 规范中关于工程工具链的设计理念：常用的重复操作应该封装成一条命令，而不是每次手动执行多个步骤。

1.2 hexo themeinit

初始化主题配置文件，将默认配置复制到用户可编辑的位置：

javascript
1
2
3
4
5
6
7
8
9
10
11
// scripts/console/lib/themeinit.js
exports.handler = async function(args) {
    const force = args.force || false;
    const legacy = args.legacy || false;

    if (exists(targetFile) && !force) {
        log.info("配置文件已存在，跳过（使用 --force 覆盖）");
        return;
    }
    // 复制默认配置到目标文件
};

1.3 hexo algolia

上传文章索引到 Algolia，支持清空重建和预览模式：

javascript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// scripts/console/lib/algolia.js
exports.handler = async function(args) {
    const client = algoliasearch(appId, apiKey);
    const index = client.initIndex(indexName);

    if (args.clean) await index.clearObjects();
    if (args['dry-run']) { /* 仅预览不上传 */ }

    const posts = hexo.locals.get('posts').toArray();
    const records = posts.map(post => ({
        objectID: post._id,
        title: post.title,
        content: post.content.substring(0, 5000),
        tags: post.tags.map(t => t.name),
    }));

    await index.saveObjects(records);
};

二、CI/CD 自动化

2.1 完整流程

目前的部署流程已经完全自动化：push 到 Gitea 后自动触发构建。

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# .gitea/workflows/publish.yaml
name: Generate and Deploy Hexo Site

on:
  push:
    branches: [main]
    paths:
      - "source/_posts/**"
      - "themes/**"
      - "_config.yml"
      - "_config.*.yml"

jobs:
  generate-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - Checkout（含 submodules）
      - 安装 Node.js + hexo-cli
      - hexo clean && hexo generate
      - hexo algolia（更新搜索索引）
      - hexo deploy（SSH 推送到服务器）

触发条件精确到文件路径 — 只有文章、主题、配置文件变动才触发构建，避免无关提交浪费资源。

2.2 主题与博客的脱钩问题

这是实际使用中唯一遇到过的坑：主题修订后忘记 push，Gitea 拉取的远端版本还是旧的，导致构建出来的博客没有最新的主题改动。解决方法就是养成习惯：改完主题先 push 主题仓库，再 push 博客仓库（更新子模块引用）。

三、CDN 与本地资源管理

3.1 双轨设计的实际使用

之前在视觉系统篇介绍过 CDN + 本地的双重机制。实际开发中基本没有切换过 — 日常写博客都在本地环境，直接用本地资源；只有在服务器上构建时才可能用到 CDN。这个设计更多是为"万一"准备的，属于防御性设计。

yaml
1
2
3
4
resource:
  enable_cdn: false        # 全局默认：本地
  highlight:
    enable_cdn: true       # 代码高亮强制 CDN（库体积大）

3.2 内置库清单

text
1
2
3
4
5
6
7
8
9
source/lib/
├── highlight.js/@11.10.0/     # 代码高亮
├── mathjax/@3.2.2/            # 数学渲染
├── font-awesome/@6.7.2/       # 图标字体
├── twikoo/@1.6.40/            # 评论系统
├── valine/@1.5.3/             # 评论系统
├── instantsearch.js/          # Algolia 搜索 UI
├── pretext/                   # Canvas 文字排版
└── prism.js/@1.29.0/          # 备用代码高亮

四、配置文档化

4.1 高内聚、低耦合的文档策略

DoraTiger 的配置文档是我个人比较满意的部分 — 一种强迫症式的、划分明确的设计：

text
1
2
3
4
配置体系三层结构：
  _config.yml（993 行）          ← 主题默认值，含所有配置项注释
  docs/CONFIG.md（1051 行）      ← 完整配置说明，按功能分章节
  _config.hexo-theme-doratiger.yml ← 用户覆盖文件，只写差异项

4.2 中英文双注释

每个配置项都采用中英文双注释，既方便中文用户理解，也方便国际用户参考：

yaml
1
2
3
4
5
6
7
# 是否开启 PV 统计
# Whether to enable PV statistics
enable: true

# 统计系统
# Statistics system: busuanzi | counter
type: "counter"

这种风格贯穿整个 993 行的配置文件 — 不是简单地写一行注释，而是每个配置项都有中英文对照，让配置文件本身就能当作文档阅读。

4.3 配置分区

配置文件按功能域分区，每个分区有清晰的边界注释：

yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# --------------------------------------------------
# 样式配置
# Style Configuration
# --------------------------------------------------
style:
  color:
    theme: "rgba(230, 119, 0, 1)"
    # ...

# --------------------------------------------------
# 评论功能配置
# Comment Function Configuration
# --------------------------------------------------
comment:
  type: "twikoo"
  # ...

这种"高内聚、低耦合"的文档策略意味着：每个功能的配置项集中在一个区域，修改某个功能不会影响其他部分。新增功能时，只需要在对应分区添加配置项，同时更新 docs/CONFIG.md 的对应章节 — 这是必要的维护流程。

五、发布流程

5.1 发布检查清单

text
1
2
3
4
5
6
7
□ 版本号更新（package.json）
□ CHANGELOG.md 更新
□ README.md / README_en.md 同步
□ 配置文档 docs/CONFIG.md 同步
□ git commit + tag
□ push 到 Gitea
□ CI 自动构建 + 部署

5.2 发布后验证

bash
1
2
3
4
5
# 确认部署成功
curl -s https://www.superheaoz.top/ | head -5

# 确认子模块指针正确
cd themes/hexo-theme-doratiger && git log --oneline -1

六、系列回顾

篇目	主题	关键词
（1）主题	Hexo 基础、主题结构、Pug 模板	入门
（2）插件	插件分类、安装、自定义开发	生态
（3）进阶功能	标签插件、数据文件、生成器、i18n	进阶
（4）架构与设计	三层配置、脚本注入、目录设计	架构
（5）视觉系统	暗色主题、Canvas 动画、响应式布局	视觉
（6）核心功能	渲染管线、侧边栏、分页、统计	功能
（7）安全与 SEO	加密、外链拦截、Sitemap、JSON-LD	安全
（8）搜索与国际化	本地搜索、Algolia、i18n、评论	搜索
（9）工程化与发布	CLI、CI/CD、配置文档、发布流程	收尾

HEXO 开发笔记系列到此完结。从基础知识到自建主题的完整实践，覆盖了一个静态博客从搭建到定制开发的全过程。DoraTiger 主题仍在持续迭代，后续有新功能会继续更新。

参考

• DoraTiger 主题 GitHub
• Hexo 官方文档
• Gitea Actions 文档
• Algolia 搜索服务