前面七篇都在「加功能」。这一篇讲怎么把主题从「能跑」变成「敢发布」:缺陷怎么治理、移动端那两次诡异故障的真实根因、以及一套让我不再怕发版的工程化流程。
一、原则:站点层的规避动作要回迁进主题
主题给自己站点用的过程中,我为了绕开问题写了不少站点层补丁(覆盖模板、注入 CSS/JS)。这些补丁是非常好的缺陷信号:
用户不得不改你的主题才能用——那多半是主题的问题。
于是有了这条原则:站点层补丁若对应主题缺陷,就把修复做进主题、删掉站点补丁;只有平台环境差异(如部署机 Node 版本)才留在站点层。
v1.1.0 一次性修掉 9 项,主题层把站点补丁全部退役。判定时的分类表:
| 现象 | 判定 | 处理 |
|---|---|---|
| 文档侧栏全展开、箭头无点击 | 真缺陷 | 修主题 |
{% tabs %} 点了没反应 |
真缺陷 | 修主题(core.js 补切换逻辑) |
| 分页在第 1 页缺 Prev 导致页码偏移 | 真缺陷 | 修主题 |
| 菜单新增项被排到末尾 | Hexo 深合并行为,非缺陷 | 主题加 menu_order 规避 |
Waline 的 server_url 不生效 |
真缺陷(v2 只认驼峰 serverURL) |
修主题(键名归一) |
| Hexo 8 依赖 ESM-only 包报错 | 环境问题,非主题缺陷 | 只补文档 |
动手前先判定「这是谁的锅」,能避免把环境问题写进主题(污染所有用户),也能避免把主题缺陷留在站点层(每个站点重复踩)。
二、一个隐蔽的配置 bug:主题自己的配置读不到
排查时发现 getConfig() 只读了站点根配置 hexo.config:
1 | // ❌ 主题 _config.yml 里的 notes.* / docs.* / post.* 全部失效 |
后果是:用户按文档在主题配置里写的参数毫无效果,而模板里直读 theme.xxx 的部分又正常——表现极其错乱。
顺带挖出两个相关问题:
- 死配置:
notes.collapsed、docs.expanded声明了却没接线,写了不生效; - 下标取值错误:
post.toc_depth用[0]/[1]取层级,遇到默认的[2,3,4]会被误判成「2 到 3 级」,正确做法是取 min/max。
配置项要么别写进文档,写了就必须接线。「声明了但没实现」的配置比没有这个配置更糟——用户会以为自己写错了。
三、移动端血案一:菜单按钮被压缩成 0 宽
现象:手机端导航栏左侧的菜单按钮看不见也点不着。
排查:用 CDP 真机口径(iPhone UA + 390×844 + 触摸模拟)测,elementFromPoint 在按钮位置命中不到它自身。
根因:.header-inner 是一个 flex 行,品牌区(logo + 标题)和右侧工具区都不收缩,于是唯一可收缩的 .nav-toggle 被溢出量压成了 0 宽度:
1 | /* 修复 */ |
flex 子项默认 flex-shrink: 1。当一个容器里所有子项都能收缩时,谁被压扁取决于内容,而不是你的意图。凡是「绝对不能被压缩」的交互元素(按钮、图标),显式写 flex: none 或 flex: 0 0 auto。
四、移动端血案二:全站链接点不动(P0)
这是整个开发过程中最值得记住的一个 bug。
现象:启用语言切换后,手机上抽屉展开,点里面的链接毫无反应;但点遮罩能正常关闭抽屉。
关键线索:JS 事件处理器正常生效(遮罩能关),只有 <a> 的默认跳转失效。
根因:上一篇末尾那段代码——
1 | document.addEventListener('click', function (e) { |
<html> 元素上也有 data-lang(当前语言状态)。closest() 会沿祖先链一路爬到 <html> 并命中,于是页面上任意一次点击都会被判定为「点了语言选项」并被 preventDefault()——全站链接失效。
1 | // 修复:语言选项改用专属属性,与 <html> 的状态属性彻底解耦 |
document 级 click 委托里,closest() 的选择器绝不能是可能挂在 <html> / <body> 上的裸属性。
这类命名冲突不会报错、不会告警,只在某个功能开启时才发作。规避办法是给交互标记加专属后缀:data-lang-option 而不是 data-lang。
五、commit 拆分:让每个提交都能构建
两个特性同时改了 helpers/index.js、_config.yml、head.ejs 等共享文件,hunk 交织,没法靠 git add -p 拆干净。我的做法:
- 把共享文件备份到仓库外;
- 手工裁成「仅特性 A」的中间态(特性 B 的文件
git checkout --回 HEAD); - 验证中间态能构建(这一步救过我一次:忘了回退父模板,导致
partial调用未注册的 helper 直接 ReferenceError); - 提交 A → 从备份恢复全部文件 → 提交 B。
引用了新 partial / 新 helper 的父模板,必须和这个 partial / helper 本身放在同一个 commit,否则中间态构建必然失败。
六、验证体系:不要相信退出码
| 层 | 手段 | 关键点 |
|---|---|---|
| 构建 | 场景脚本批量构建 | 判成功用 [ -s public/index.html ],退出码恒为 0 |
| 静态 | Node 脚本读产物做断言 | 属性断言只取 <html ...> 开标签(内联脚本源码是假阳性大户) |
| 运行 | 无头 Chrome + CDP | 真实点击、UA 模拟、elementsFromPoint 查层叠 |
三个让我吃过亏的脚本细节:
rm -rf会静默失败:目录里有文件被残留进程占用时,删除整体中止且返回非 0,脚本继续跑就读到上一轮的旧产物 → 得到假结果。修复:clean_out()显式校验目录真被删掉,失败直接exit 1。- 清理必须验证结果——上面这条的通用教训:任何「清理」步骤都要断言它真的成功了,否则污染会伪装成被测对象的缺陷。
pkill -f会匹配到自身包装进程而挂住:用 PID 精确 kill。
七、发布:SemVer 与 npm
版本规则:新功能升 MINOR,仅修 Bug 升 PATCH。v1.3.0 因为含 feat(floating) 取 MINOR,不是 1.2.1。
流程:
1 | # 1. 升版本 → 2. 构建验证 → 3. 发布 |
本机有 https_proxy 时,npm view 会命中 Cloudflare 缓存(响应头 CF-Cache-Status: HIT),发布后长时间查不到新版本,其实版本早已上线。
用 curl --noproxy '*' https://registry.npmjs.org/<pkg> 直查才是准的。npm 本身也有 1–3 分钟的处理延迟,所以脚本要轮询而不是查一次就判定失败。
发布后一定要下载 tarball 抽查:files 白名单漏掉某个目录时,npm publish 不会报错,用户装到的就是个残包。
八、回头看:这套方法能迁移吗
能。八篇下来真正沉淀的不是某个 Hexo API,而是几条通用做法:
- 形态差异配置化,让升级不产生合并冲突;
- 模板只做分支,计算下沉到 helper;
- 先定档再出布局,把状态写进
<html>属性,CSS 只读属性; - 站点层补丁是缺陷信号,定期回迁;
- 验证要断言产物而非退出码,清理步骤必须自检;
- 每个 commit 都能独立构建。
如果只能带走一条,我选第 5 条——「看起来成功」比「失败」危险得多,因为失败会拦住你,而假成功会让你把错误发布出去。
系列导航
系列总入口 · 上一篇:运行期多语言切换与 AdSense · 回到第一篇:为什么再造轮子
评论