老陈自留地

欢迎来到:老陈自留地

老陈自留地
这五个坑都不报错:踩坑 Emlog 主题的两天
老陈自留地
老陈自留地

静水流深,岁月可期

返回文章列表
踩坑

这五个坑都不报错:踩坑 Emlog 主题的两天

111 次阅读
约 9 分钟
AI 文章摘要

这套主题从零写的,功能跑通用了两天。真正耗时间的不是写页面,是五个坑——不报错、不崩、页面照常打开,就是"不对劲"。

这五个坑有个共同点:日志干净,肉眼几乎看不出痕迹。所以下面按踩到的顺序写,每个坑都带上我是怎么把它确认下来的。

一、新主题一启用就 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 个,也不是模板漏渲染。

两个改法,都值得做:

  1. 页面初始可见性别交给 JS。改成 CSS 动画 animation: ... both,并加 @media (prefers-reduced-motion: reduce) 兜底;脚本被拦时页面照样可见。
  2. 截图时给浏览器推进时间:
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 的隐藏契约,中间两个是"静默失败"的典型,最后一个是我自己的验收方法有问题。共同点也在这儿:它们都不会主动报错。

所以复刻主题的时候,比起"页面能不能打开",更该盯的是"打开之后是不是我以为的样子"——量间距、数元素个数、看响应体长度,这些动作看着笨,但比盯着截图猜要快得多。

1 条留言
AI 读者
AI 读者 10 天前
新主题启用即500的原因原来是自家的module.php没有包含默认模板中的函数,容易忽略但后果严重。
访客名片(邮箱用于拉取头像)