PagedJS报paged.polyfill.js item doesn't belong to list错误排查

页面运行时控制台抛出Promise上下文未捕获异常：Uncaught (in promise) Error: item doesn't belong to list，报错定位到paged.polyfill.js文件。
项目中引入PagedJS实现PDF导出HTML模板的统一页眉、页脚能力，相关功能代码此前连续一周正常运行，未做任何代码改动的情况下从当日开始持续弹出上述错误。
控制台报错参考截图：

对应业务实现代码：

<script src="https://unpkg.com/pagedjs/dist/paged.polyfill.js"></script>
<script>
class MyHandler extends Paged.Handler {
    constructor(chunker, polisher, caller) {
        super(chunker, polisher, caller);
    }
    beforeParsed(content) {
        // 章节计数器初始化
        $("head").append(`
            <style>body{counter-set: chapters ${content.querySelectorAll(".chapter").length};}</style>
        `);                        
    }
    afterPageLayout(pageFragment, page){
        // 不存在page类的页面直接隐藏
        if(pageFragment.querySelectorAll(".page").length == 0){
            console.log("Hiding page!");
            console.log(pageFragment);
            pageFragment.setAttribute("style", "display:none;");
        }
    }
}
Paged.registerHandlers(MyHandler);
</script>

• 根因定位：报错触发有两个叠加因素：
  1. 你在afterPageLayout钩子中直接给pageFragment设置display:none的操作，只修改了DOM显示状态，没有同步更新PagedJS内部维护的分页节点链表，后续PagedJS遍历分页列表做排版计算、PDF渲染时，会校验节点与列表的归属关系，找不到对应节点归属时就会抛出该错误。
  2. 你引用的是unpkg源的latest版本PagedJS，CDN会自动拉取最新发布的包，近期PagedJS版本更新新增了节点链表归属校验逻辑，旧版本无该校验时手动修改DOM不会抛错，更新后原有不规范的DOM操作就会稳定触发报错，这也是代码没改动却突然出问题的核心原因。
• 修复方案1（推荐，无侵入）：移除钩子中手动操作DOM隐藏空页的逻辑，改为通过CSS规则控制空页隐藏，完全不触碰PagedJS内部维护的DOM结构，不会触发内部校验。在beforeParsed注入的样式中追加对应规则即可：

/* 隐藏无有效内容的空页 */
.pagedjs_page:not(:has(.page-content .chapter)) {
    display: none !important;
}

• 修复方案2（需要DOM操作场景）：如果必须在钩子中处理页面节点，不要手动修改样式，调用PagedJS官方提供的页面移除API，保证内部链表状态与DOM同步：

afterPageLayout(pageFragment, page){
    if(pageFragment.querySelectorAll(".page").length == 0){
        // 调用官方API移除空页，禁止直接操作pageFragment的display属性
        this.caller.removePage(page);
    }
}

• 长期优化建议：生产环境引入PagedJS时锁定具体版本号，不要直接拉取latest版本，避免第三方包无感知更新引发线上故障。

内容的提问来源于stack exchange，提问作者Shuichi