Troubleshooting ZH

排错与兼容性

文档首页 · English

查看导出失败原因

导出进度窗口会显示错误。关闭窗口后，用命令面板运行「检查插件状态与导出环境」，查看 errors 和 lastPdfExport；点击「保存诊断 JSON 到导出目录」保存到默认 _exports/academic-diagnostics-*.json。错误历史保留在当前插件会话，重载前请保存。pdf.interfaceAvailable 只检查接口存在，不代表导出成功。成功导出才会生成 .report.json；失败时 .phb.html 快照可能已经保存。更完整的日志可在 Ctrl+Shift+I 的 Console 中搜索 [Academic Notes]。

排错与兼容性

常规诊断中的 indexPerformance 会显示最近一次索引的读取、复用、重新解析和视图刷新数量，以及耗时与是否重建编号图。可见段落状态则说明 KP 已生效、保留原生编辑/选区、内容或样式不支持、达到处理上限，还是无法安全排满；不记录段落文字。

遇到编辑或滑动异常时，可以运行 暂停或恢复实时预览增强（本次会话），临时暂停编辑视图中的插件引用替换与 KP/缩进增强。阅读和导出继续可用，原文与已保存的偏好不变，再运行一次即可恢复。这是隔离原因和尝试恢复的工具，不代表已保证修复所有 iPad 或宿主滚动异常；仍可配合原有 90 秒诊断记录提供真实设备证据。

记录本机断行或滑动异常

如果 Proof 行尾参差或实时预览无法上下滑动，先打开有问题的笔记，在命令面板运行 「开始记录排版与滚动诊断（90 秒）」。先在阅读视图停留几秒，让有问题的段落出现在屏幕上，再切换实时预览、编辑 Proof 标题或正文并尝试滑动。保持同一篇笔记打开。可运行 「停止并保存排版与滚动诊断」，或等待 90 秒后自动停止。

记录立即保存，此后每 15 秒保存一次，文件为 _exports/academic-layout-diagnostics-*.md；如果你改过导出目录，则保存在设置的库内目录。即使必须重启应用，已经保存的检查点仍会保留。把 iPad 报告发给排错者，也可以在电脑录一份作对照；不需要 Mac 或远程开发工具。报告是包含 JSON 代码块的普通 Markdown 笔记，通过库 API 创建并在保存后读取校验。请在笔记库根目录查找，而不是插件文件夹。原有诊断窗口提供开始／停止、「查看记录」和「打开已保存报告」按钮；即使写入失败，仍可在窗口查看本次记录。旧 .json 报告可能被 Obsidian 的不支持文件过滤隐藏。

只有手动运行命令才开始记录。内容包括可见环境的尺寸、字体与排版／滚动样式、是否存在 KP 标记、实际行尾空隙、选区位置、触摸／滚动事件是否被其他处理器阻止、节点变动计数及插件排版活动。还记录视口尺寸变化和匿名的触点目标检查，帮助排查键盘／遮挡；记录期间只分类笔记外的触摸／指针事件，不记录其内容。记录有数量上限，停止或卸载插件会清理监听。不保存笔记文字、公式源码、文件名、块 ID、HTML、输入值或错误消息，不自动上传；不会改动笔记、主题、KP 开关或光标。报告包含字体／样式和设备／版本信息，分享前仍可自行检查 JSON。

没有 KP 标记的原生段落沿用浏览器断行。KP 开关默认关闭，阅读与实时预览须分别确认。诊断负责收集证据，不代表已修复 iPad 卡滚动。

问题	检查
公式未编号	默认仅编号被引用公式；检查 ID、路径、排除设置和 \notag
引用未替换	手写别名默认保留；源码模式不替换；重复 ID 不解析
数学框或图表异常	停用重复的编号插件/数学框 CSS/布局片段，确认支持的 Callout 类型
框内颜色偏差	检查是否选择跟随主题；普通正文色开关只控制文字
Electron 接口不可用	运行「检查插件状态与导出环境」，更新 Obsidian 桌面安装程序
PDF 导出失败	查看进度窗口和报告；确认图片已存入库、公式和字体可正常加载
编号没有刷新	运行重建索引命令

同一个插件可在桌面和 iPad 上安装。移动端提供数学环境、编号、跨文件引用、目录、外观设置和 HTML 快照；PDF 命令只在桌面版显示，使用 Obsidian 自带的 Electron。最低应用版本 1.9.0 表示 API 下限，不代表所有设备组合都已实机验收。目前自动化覆盖包括模拟 Obsidian 宿主、发布包无 Node／Electron 加载和独立 WebKit 横／竖屏回归测试，仍需在真实 iPad 上确认。若社区插件目录尚未显示本插件，可等待目录条目更新，或把发布页的三个安装文件同步到库内 .obsidian/plugins/academic-notes/ 后在 iPad 的社区插件设置中启用。

可用合成的移动端验收笔记，在真实 iPad 应用内检查编辑、键盘切换及滑动。