这套主题从零写的,功能跑通用了两天。真正耗时间的不是写页面,是五个坑——不报错、不崩、页面照常打开,就是"不对劲"。
这五个坑有个共同点:日志干净,肉眼几乎看不出痕迹。所以下面按踩到的顺序写,每个坑都带上我是怎么把它确认下来的。
一、新主题一启用就 500,但日志里什么也没有
从零仿写 Emlog Pro 主题,最容易在第一天就撞这个。表现为启用新主题后整站 500,PHP 错误日志里却没有能指向主题的线索。
根因是官方 default 模板把一批函数写在了它自己的 module.php 里,比如 blog_tool_ishome()、getEmUserAvatar()。这些函数不属于核心,只属于默认模板。你复制一份新主题出来,等于没有继承它们,模板一调用就 fatal。
所以复刻的第二步(第一步是拷目录)一定是:打开默认模板的 module.php,从头到尾看一遍它定义了哪些函数,然后在自己的 module.php 里补齐。
// 自己的 module.php 里,按需重写,不要假设核心里有
if (!function_exists('blog_tool_ishome')) {
function blog_tool_ishome() {
// 自己实现
}
}
function_exists 这层守卫值得加,因为 Emlog 升级后这些函数有可能被挪位置。
二、404.php 返回了 404,但响应体是 0 字节
第二个坑更隐蔽。我的独立模板 404.php 状态码是对的,页面却是完全空白,一开始以为是路由或伪静态的问题,翻了一圈 rewrite 规则,全是白费。
真相是:主题根目录下的 404.php、pw.php 这类独立模板不经过 header.php,所以主题的公共模块根本不会自动载入。文件里没有 require 它,函数自然调不到,于是输出空。
<?php
require_once View::getView('module');
// 下面才是模板内容
顺带记一下对独立页面模板有用的东西:专属模板靠文件头注释被后台识别(/*@name 友链页面*/),页面数据里用 blog.template 存模板名;而模板里能用的变量只有 $log_title、$log_content、$date、$logid、$comnum、$comments、$ckname、$ckmail、$ckurl、$verifyCode、$allow_remark、$logData 这一批。$top、$sortid 在页面模板里是没有的,直接引用会报未定义,得用 isset() 兜着。
三、加了个 utility 类,样式一点没变
这是我后来才意识到最坑的一个:前台只加载一份预编译好的 utility CSS,本机又跑不起构建。于是我顺手在模板里加了个 pt-4、aspect-square 之类的类——不报错,不警告,就是没效果。
因为这个类在编译产物里压根不存在。
确认方法很土但可靠,动手前先搜一遍产物:
# 类名带点,注意转义与花括号的写法
grep -c '\.pt-4{' assets/css/tailwind.css
是 0 就别用了,改成自定义组件类,并且把同一段 CSS 同时写进源文件和编译产物末尾,两处保持一致。我改成 .corner-badge--pin 这类自有类名后,问题消失。
这类失效最阴的地方是它只差一点点。置顶小胶囊和标题实测只差 1px 就被压住了,1200 宽截图里几乎看不出来,最后是靠量矩形才发现的:
(() => {
const p = document.querySelector('.corner-badge--pin');
const h = document.querySelector('#posts-container h3');
return JSON.stringify({
gap: h.getBoundingClientRect().top - p.getBoundingClientRect().bottom
});
})()
11px 级的小胶囊、角标,建议显式写 line-height: 1,不然默认行高在窄屏一挤就变样。
四、打字机只在直达页面时动,点链接进去就不动
主题骨架是 PJAX 无刷新的,页面不整页重载。我加了逐字出现的正文动画后,出现一个很典型的症状:直接访问文章页正常,从首页点进来不动。
原因是有两个初始化入口:一个是首屏的 DOMContentLoaded,另一个是每次 AJAX 跳转完成后统一调用的刷新函数(我这个主题里叫 lcbkRefreshContent)。我只注册了第一个,所以"跳过去"这条路径永远走不到。
document.addEventListener('DOMContentLoaded', initTypewriter);
window.lcbkRefreshContent = (function (orig) {
return function () {
orig && orig.apply(this, arguments);
initTypewriter();
};
})(window.lcbkRefreshContent);
还有一个细节:模板里别把全文写进标签内。否则脚本先清空再逐字补,用户会看到整段文字闪一下再从头打。正确做法是标签留空、正文放在 data-text 里,由脚本读出来再加。另外别忘了 prefers-reduced-motion 直接输出全文的分支,以及重入时清掉上一个定时器。
五、用 headless 截图验收,被自己的动画骗了
最后这个坑不是代码问题,是验收方法的问题。
我习惯用 Edge headless 截图检查页面,结果截出来整页发灰、半透明,列表还只显示前几项。第一反应是"入场动画没跑完"——方向是对的,但结论是错的:不是动画有问题,是截图抓得太早。
如果页面初始可见性靠 JS 移除 opacity-0 来实现,headless 截图时脚本还没跑(或者被延时挡住),你拍到的就是半透明状态。同理,延时入场的列表项只出现了 6/17 个,也不是模板漏渲染。
两个改法,都值得做:
- 页面初始可见性别交给 JS。改成 CSS 动画
animation: ... both,并加@media (prefers-reduced-motion: reduce)兜底;脚本被拦时页面照样可见。 - 截图时给浏览器推进时间:
edge --headless=new --disable-gpu --no-first-run --hide-scrollbars \
--virtual-time-budget=2000 --user-data-dir=/tmp/prof-$$ \
--window-size=1440,1900 --screenshot=out.png "$URL"
加了 --virtual-time-budget 之后,同一页面上原本"只出现 6 项"的列表完整了,半透明也没了。
顺带一个判断顺序:截图可疑时,先用不带动画的静态页对比一次、或放大局部看一眼,确认是抓帧问题再重截,确认是代码问题才改样式。不然很容易把好代码改坏。
六、小结
| 坑 | 症状 | 真正的原因 |
|---|---|---|
| 主题启用即 500 | 整站白屏,日志无线索 | 默认模板的私有函数不继承 |
| 独立模板空白 | 状态码正常,响应 0 字节 | 没 require 主题 module.php |
| utility 类无效 | 不报错,样式不动 | 类不在预编译产物里 |
| 打字机失效 | 直达正常,跳转不动 | 只注册了首屏入口,漏了刷新函数 |
| 截图看走眼 | 整页半透明、列表缺项 | headless 抓帧太早,不是样式问题 |
这五个里,前两个是 Emlog 的隐藏契约,中间两个是"静默失败"的典型,最后一个是我自己的验收方法有问题。共同点也在这儿:它们都不会主动报错。
所以复刻主题的时候,比起"页面能不能打开",更该盯的是"打开之后是不是我以为的样子"——量间距、数元素个数、看响应体长度,这些动作看着笨,但比盯着截图猜要快得多。