看板娘不拖慢首屏：六个脚本的串行注入，与三重触发时机-知集

阅读约 33 分钟9,857 字

摘要：给站点加了一只 Live2D 看板娘。它要加载 6 个脚本加模型贴图，总量好几 MB —— 直接挂在 head 里，首屏就得等它。本文讲清两件事：为什么这 6 个脚本必须串行加载（并行会得到一个「本地必现不了、线上偶发」的顺序 bug），以及怎么用三重触发时机把它和首屏彻底解耦（load 后延迟、定时兜底、点击提前）。附一份零依赖交付代码与验证方法。
适合阅读：往页面里加过第三方库/重型组件的开发者，尤其是遇到过「偶发 X is not defined」的人。

一、先摆正定位：它是「增强」，不是「页面的一部分」

看板娘是装饰性功能。它的价值在于「页面已经能用了之后，多一个可爱的存在感」，而不是「页面能用」本身。所以任何「为了让它出现而让用户多等」的做法都是错的定位。

在这条原则下，实现目标就很清楚：

目标	做法
不占首屏	脚本不在 head 注册；等 `window.load` 之后再启动
不错过时机	再设一个定时兜底，防止「load 事件永远不会来」
用户想早点看	点击容器立即启动，不等待
只启动一次	三重触发共用一个 `loaded` 闸门

二、六个脚本必须串行：一个「本地复现不了」的顺序 bug

Live2D 这套库由 6 个文件组成，它们之间是有严格依赖顺序的：

TweenLite.js          // 动画补间
live2dcubismcore.min.js   // Cubism 运行时核心
pixi.min.js               // 渲染引擎
cubism4.min.js            // Cubism 4 适配
pio.js                    // 看板娘主程序
pio_sdk4.js               // 与 cubism4 的桥接

最自然的写法是一次循环全部插入：

// ✗ 并行插入：浏览器不保证执行顺序
libs.forEach(function (src) {
    var s = document.createElement('script');
    s.src = src;
    document.head.appendChild(s);
});

问题在于：动态插入的 <script> 默认是异步执行的，执行顺序取决于哪个文件先下载完。小的先到、大的后到，于是时快时慢。于是你会得到一个很折磨人的现象：

本地刷新十次都正常，线上偶发 pio is not defined；清理缓存重试又好了。—— 因为它依赖的是「网络到达顺序」这个不确定的东西。

修法：一个 onload 之后再插下一个

var i = 0;
function next() {
    if (i < libs.length) {
        var s = document.createElement('script');
        s.src = libs[i++];
        s.onload  = next;    // 前一个加载完成，才插下一个
        s.onerror = next;    // 🧨 单个文件 404 也不阻塞后续
        head.appendChild(s);
        return;
    }
    start();                 // 全部就绪，启动
}
next();

这段代码很土，但它是唯一不依赖浏览器行为差异的写法。Promise、async/await 也能做到，但收益不大——这里要的只是「严格顺序 + 单个失败不阻塞」。

注意 s.onerror = next 这一行：某个库 404 时，后面的继续加载。让它卡死在这里，比缺一个库更糟——卡死时你什么都看不到，继续加载至少能进到报错的那一步。

三、三重触发时机：为什么一个不够

「什么时候启动」看起来只需要一个答案，实际上有三个场景要覆盖：

触发	时机	解决什么
① 首选	`window.load` 之后 + 2.5s	让首屏彻底稳定（load 之后浏览器还在解码图片、跑首屏脚本）
② 兜底	页面开始后 4.5s 的定时器	load 事件可能永远不来（某个资源挂住）或已经错过
③ 提前	用户点击看板娘容器	用户主动想看，不该让他等

第②条最容易被忽略。它的存在理由有两个：

· load 可能永远不触发——只要页面上有任何一个资源（图片、字体、第三方统计）挂在那里不返回，load 就一直不触发。这时候如果没有兜底，看板娘就永远不会出现，而你以为是自己代码写错了；

· load 可能已经错过了——如果这段脚本本身是在 load 之后才被插入执行的（比如被包在别的延时逻辑里），那么 addEventListener('load') 注册得太晚，事件早就过去了，回调永远不会被调用。

三条路径都指向同一个 boot()，所以必须有一个闸门：

var loaded = false;
function boot() {
    if (loaded) { return; }   // 🧨 三重触发共用闸门
    loaded = true;
    // ... 串行加载六个脚本
}

教训：「事件 + 定时兜底 + 用户主动」是异步初始化最稳的三件套。单靠事件，会漏掉「事件不来 / 事件已过」；单靠定时，会让用户觉得慢；加上主动触发，才覆盖完整。任何一条单独用，都会在某个边缘场景里失败。

四、两个小地方，但都会「静默失效」

① 容器要被提到 body 顶层

看板娘的容器是在 wp_footer 输出的，位置取决于主题的模板结构——很可能被套在一个带 overflow:hidden 或 transform 的容器里。那样一来看板娘的定位基准就不是视口了，会出现「位置偏了」「被裁掉一半」甚至「完全看不见」。

function hoist() {
    var c = document.getElementById('zdw-pio-container');
    if (c && document.body && c.parentNode !== document.body) {
        document.body.appendChild(c);   // 提到顶层，定位才可靠
    }
}

② 资源路径绝不硬编码

早期版本把资源地址写成了完整 URL（含域名和主题目录名）。后来换域名、改主题目录名，看板娘就静默消失了——页面照常打开，控制台只有一串 404，而页面上看不出任何异常。

// ✗ 硬编码：换域名/改目录名即失效
$base = 'https://old-domain.com/wp-content/themes/old-theme/assets/live2d/';

// ✓ 由主题 API 拼出来，并用 is_dir() 兜一层
$dir = get_stylesheet_directory() . '/assets/live2d/';
$url = get_stylesheet_directory_uri() . '/assets/live2d/';
$base = is_dir($dir) ? trailingslashit($url) : '';
// 目录不存在 → 什么都不输出（比在页面上挂一串 404 干净）

教训：硬编码的路径不会「报错」，它只会「换个环境就不见了」。这类问题的症状特别像「功能没做」，排查时容易被带偏到 JS 逻辑上。判断方法很直接：资源 404 与逻辑报错，在 Network 面板里长得完全不同。

五、这类功能怎么验证

层次	做法	能发现
首屏请求	DevTools Network 按「开始时间」排序，看首屏阶段有没有这 6 个脚本的请求	懒加载到底生不生效
调度逻辑	用假定时器推进时间，断言 `boot()` 只在正确时机被调用一次	三重触发的闸门是否正确
开关	关掉开关后页面里不应出现容器与脚本	开关没接上
路径	在页面 HTML 里 grep 资源基址，确认不含域名/主题目录名	硬编码残留

这里要特别说明一条做不到的事：不要指望用无头浏览器 + DOM 断言去验证 Live2D 本身。它走 WebGL，无头环境里通常拿不到绘图上下文，画布必然是空的——这不是代码坏了。能自动化的只有「调度逻辑」这一层（用假定时器），而「画得对不对」必须靠人眼看。

承认哪些能自动化、哪些不能，也是工程判断的一部分。把不能自动化的部分硬塞进测试，只会得到一堆假失败。

六、小结：装饰性功能的三条纪律

把看板娘这件事抽象一下，其实就是「怎么往页面里加一个重型装饰组件」。三条纪律：

#	纪律	理由
1	把它排在首屏之后	装饰不该和内容抢带宽与主线程
2	给它至少两条触发路径	事件会不来、会错过，需要定时兜底
3	让路径可计算，别写死	硬编码不会报错，只会换个环境就不见了

顺带一条更普适的观察：这类功能的 bug 几乎都不在「主逻辑」上。Live2D 怎么渲染、怎么交互，那是库的事；真正会出问题的，永远是加载顺序、触发时机、资源路径这些”外围”的东西——因为它们没人会专门去测。

此处内容已隐藏，请付费后查看