这是 hexo-theme-xfm 的开发过程系列,记录这套主题从首次提交(efc52bd)到 v1.3.0 的完整路径:设计决策、真实代码,以及调试到怀疑人生的那些坑。
一句话
一套代码、一套令牌、一份配置,长出 blog / notes / docs 三种形态,全站零第三方运行时依赖。
全系列篇目
| # | 篇目 | 你会拿到什么 |
|---|---|---|
| 一 | 为什么再造轮子与三模式架构 | 需求定位、三模式的本质差异、目录分层、三条设计原则 |
| 二 | Hexo 8 主题开发的九个坑 | 插件不加载、脚本不回调、配置读不到、EJS 的 TDZ、page.path 形态、没有 cheerio |
| 三 | 设计令牌体系 | 三层令牌、品牌色 RGB 派生、深色只换变量、z-index 集中管理 |
| 四 | 三模式外壳的形态分发 | mode 优先级、挂件栏 vs 导航树、空态守卫、body class 抽查法 |
| 五 | 从响应式到自适应式响应 | 为什么删掉宽度 @media、四级定档链、档位样式生成器、旧配置兼容 |
| 六 | 标签插件与内容过滤器 | 14 个标签的实现、跨标签状态收集、占位保护 + 正则 |
| 七 | 运行期多语言切换与 AdSense | 反查替换、白名单容器、占位符重渲染、广告位统一判定 |
| 八 | 从可用到可靠 | 缺陷回迁、两个移动端血案、commit 拆分、验证体系、npm 发布 |
建议的阅读顺序
先建立整体图景
先读「为什么造」和「形态如何分发」,理解三模式不是三套皮肤,而是三种信息结构。
再补地基
踩坑清单和设计令牌是后面所有实现的前提。写过 Hexo 插件的人可以跳过第二篇的前半部分。
然后攻难点
自适应档位、标签插件、国际化,这三块是主题里最复杂的部分,各自独立,可挑感兴趣的读。
最后看工程化
缺陷治理与发布流程。如果你也要长期维护一个开源项目,这篇的方法论比代码更有价值。
适合谁
- 想写自己的 Hexo 主题:第二、四篇能帮你少踩一半的坑;
- 想改主题但不想 fork:第四篇讲
theme_config覆盖与深合并行为; - 关心前端架构:第三、五篇的令牌分层和档位驱动是通用的;
- 维护开源项目:第八篇的回迁原则、commit 拆分与发布流程可直接照搬。
相关资源
版本对应
本系列基于 v1.3.0 撰写。主题仍在迭代,若某处与你装到的版本不一致,以 主题仓库 的 CHANGELOG 为准。
姐妹系列
另一套主题
从零造一个机构官网主题(xongyi) —— 面向企业 / 政务 / 教育官网,8 篇讲三套预设、首页板块编排、配置产品化与五平台部署。
两套主题的差异对比见 那一系列的收官篇。