故障排查

快速分流

现象	优先检查
没有阅读器入口	脚本启用、站点匹配、刷新、重复脚本
主题打不开	原生页面是否可打开、请求数据、当前主题缓存
打开过程中显示自动恢复	等待当前倒计时；反复失败时查看请求数据
跳不到楼层	过滤状态、目标是否删除、虚拟窗口是否仍在补齐
图片打不开	预览是否存在、原图源、来源楼层、资源缓存
持续 429	请求数据、端点冷却、性能设置是否高于默认、Cloudflare
设置异常	先导出，再按范围重置
页面卡顿	DOM 数量、媒体、长任务、当前性能设置

入口没有出现

1. 地址必须属于 LINUX DO 或 20 个其他内置社区；其他标准 HTTPS Discourse 还须在脚本管理器中为本脚本添加该域名的用户匹配或站点访问。已保存的自定义站点只负责识别兜底，不会自行扩大 @match。具体范围见安装与更新。
2. 确认脚本和站点访问权限已启用。
3. 安装/更新后完整刷新。
4. 停用重复的正式版、本地版或同类接管脚本。
5. 从脚本管理器确认版本为 1.6.4；刚完成更新但页面仍显示旧版时，请完整刷新已打开页面。

主题或楼层无法加载

先用标题栏入口打开原生页面：

• 原生页面也失败：更可能是权限、网络、帖子删除或站点状态。
• 原生正常、阅读器失败：查看“请求数据”的异常和排队原因。

目标楼层 404/410 时，阅读器把它记为当前会话不可用，避免反复请求。只看楼主或其他筛选可能隐藏目标；消息跳转会尝试解除不兼容过滤。

在“设置 → 日志记录 → 请求记录 → 帖子与楼层诊断”中核对：

• “虚拟窗口”显示离屏停放或惰性 DOM：属于正常资源控制，不是嵌套关系丢失；
• “缓存”显示 canonical stream 正文缺口：等待同一补流链，不要先清空全部缓存；
• “已删除楼层”列出楼层号：原站确认 404/410 后当前会话不会重复请求；
• “网络”或“429 / Cloudflare”异常：按对应调度状态等待或完成验证。

若仅一个主题异常，使用“数据管理”清理当前主题缓存，而不是清空全部历史。

1.6.1 会在用户仍在滚动时合并虚拟窗口提示，并把请求水合、图片和回复线导致的尺寸写回延迟到停稳后一次提交。快速滑动长帖时偶尔看到离屏骨架属于正常预备状态；如果停稳后仍持续空白或反复跳位，再记录主题路径、目标楼层和“帖子与楼层诊断”中的虚拟窗口状态。

打开中断与自动恢复

主题打开遇到短暂网络中断、超时或服务器 5xx 时，阅读器会保留外壳并自动重试。当前等待顺序为约 1 秒、2 秒，最多自动重试两次；新的打开事务、关闭阅读器或销毁运行时都会中止等待。

自动重试仍失败时，加载区保留分类后的恢复入口：“重新加载”复用原目标事务；Cloudflare 失败另提供手动验证链接；也可直接关闭阅读器。恢复过程不会刷新整页、清理缓存或伪造已加载楼层。

以下情况不会走这条自动恢复链：

• 429：继续由请求调度和端点冷却处理，避免自动重试绕过退避；
• 不可恢复的 4xx：直接显示失败信息和“重新加载”；
• 登录、权限、主题删除或 Cloudflare 验证：需要先处理对应原因。

切换到新帖子失败时，原帖子会继续保留，失败页不会覆盖仍可阅读的 active Topic。自动恢复持续出现时，不要同时重复点击刷新；先打开“设置 → 日志记录 → 请求记录”查看请求类型、状态和冷却原因，最终失败后再使用错误页的“重新加载”。

图片和媒体

点击正文图片打开灯箱；若原图或评论未加载，先在工具栏重试并核对当前站点权限，关闭灯箱不会改变正文或下载记录。

• 预览能看、原图失败：原图地址可能过期、受权限限制或被跨域阻止。
• 来源楼层 404：已有 CDN 图片仍可能可用，不应无限重试来源。
• HLS 失败：检查浏览器编码支持、媒体服务器和网络策略。
• 公式缺失：检查 KaTeX 外部依赖是否加载。

先打开“设置 → 日志记录 → 请求记录”的“图片与媒体诊断”：

• “图片加载”只统计当前挂载楼层的真实失败和正在重试，并列出所属楼层；
• “资源缓存”显示 canonical 图片目录完整度、本会话 Object URL 和持久 Blob 缓存状态；
• “来源楼层”区分图片仍可访问但来源楼层已被 404/410 删除；
• “音视频 / HLS”显示当前源、活动播放器和原生/Hls.js capability，并关联最近脱敏媒体请求错误。

清理“头像与图片”缓存后重新打开；这不会删除线上图片。

429 和 Cloudflare

从“设置 → 日志记录 → 请求记录”确认失败类型和冷却状态；429 或 Cloudflare 恢复期间保持页面可见并等待调度器解除暂停。

1. 不要连续刷新或重复点击加载。
2. 切回“均衡”或“省资源”。
3. 等待请求数据面板显示冷却结束。
4. 若出现 Cloudflare 验证窗口，在唯一窗口内完成验证。
5. 验证成功后让阅读器逐步恢复，不要立刻开多个长帖。

单个端点异常会独立冷却；若所有请求都慢，检查全局窗口或宿主请求活动。

配置恢复

配置异常时先导出当前非秘密设置，再导入已知有效文件或恢复默认；缓存清理是独立操作，WebDAV 凭据、历史和原站数据不会随设置重置。

顺序：

1. 导出当前设置。
2. 只重置相关设置组或清理相关缓存。
3. 让设置立即投影，或重新打开被清理的主题/面板后复现。
4. 最后才使用“恢复全部默认”。

导入与恢复默认都先完整确认；组合写入失败时会恢复已经写入的设置，无效文件或取消不会形成部分结果。恢复默认会覆盖普通偏好、其他适用站点、翻译和 WebDAV 设置并清除其中的本机凭据，但保留“不想再看”的手动记录、自动过滤历史与自动过滤设置，也不会删除阅读队列、离线下载、缓存、浏览历史或原站账号数据。

提交有效问题报告

包含：

• 浏览器、脚本管理器和脚本版本；
• 页面类型与路径，不含私密查询参数；
• 最短复现步骤；
• 预期和实际结果；
• 请求数据中的状态、类型和排队原因；
• 已脱敏截图。

不要包含 Cookie、Authorization、私信/通知正文、完整 API 响应或可识别账号信息。