Troubleshooting

故障排查

本页按“片段、文献、预览”三部分排查 TeXLeaf 0.7.1。多数问题可以通过确认文件作用域、设置覆盖、第三方扩展和 Output → TeXLeaf 日志定位。

先做这六步

1. 确认安装的是 GitHub Release 中的 texleaf-0.7.1.vsix，不是旧本地构建。
2. 运行 Developer: Reload Window。
3. 在 Settings 搜索 @ext:local-lab.texleaf，检查目标功能总开关。
4. 检查设置右侧齿轮的“Modified in”来源；工作区/语言设置可能覆盖用户设置。
5. 打开 View → Output，选择 TeXLeaf，复现一次问题。
6. 若怀疑扩展冲突，在临时 Profile 或通过 Help: Start Extension Bisect 比较。

不要在含未保存工作时随意删除 Profile/globalStorage。管理器和恢复命令已经提供冲突检查与备份。

片段没有展开

依次检查：

• 文件是否已经保存；
• 后缀是否正好是 .tex 或 .bib，而不是 Untitled、.md、.tex.md；
• 右下角 language mode 是否在 texleaf.languageIds，默认 latex、tex、bibtex；
• texleaf.enabled 是否为 true；
• 自动规则需要 texleaf.autoSnippets=true；
• 非自动规则需要按 texleaf.manualTrigger 对应的 Tab 或 Space；
• t/m/M/n 是否符合当前位置的文本、行内数学或块级数学；
• 当前环境是否在 texleaf.excludedEnvironments；
• “问题”面板是否有 JSONC、正则、选项或占位符诊断。

对于 dm、\thm、\dfn、\lem、\cor 和四个模板，即使自动事件偶发被输入法或 Suggest 打断，完整输入 trigger 后按 Tab 应走 TeXLeaf 精确兜底。

;a 在 equation 里不展开

如果位置在以下参数中，这是预期保护：

\label{;a}
\tag{;a}
\tag*{;a}

闭合参数后，外层数学环境会恢复。如果在普通公式正文仍不展开，检查是否处于注释、verb/verbatim 或被排除环境。

\thm 在 Suggest 中不是第一项

出厂 \thm 是自动规则，通常完整输入即展开；Tab 精确兜底不依赖普通 Suggest 排名。若只看到 LaTeX Workshop 的命令候选：

• 确认没有关闭 texleaf.autoSnippets；
• 确认当前是文本模式；
• 在管理器中检查 environment.theorem 是否启用、trigger 是否被自定义；
• 按 Tab 验证 exact path；
• 在快捷键页检查 Tab 是否被其他扩展更高优先级接管。

dm 有时自动、有时不自动

dm 使用文本模式和词边界。它不会在较长单词内部、数学区域、Untitled 或不受支持文件中展开。中文输入法 composition 期间，扩展会避免对尚未提交的组合文本重复处理；提交完成后如仍未展开，按 Tab，并附最小复现报告。

自动分数、括号与 Matrix

1/2 没变成分式

• 需要数学区域；
• texleaf.autoFraction=true；
• 输入第一枚 / 后保留 1/ 是正常的，首个有效分母字符 2 到来时才变换；
• 左侧扫描遇到 autoFractionBreakingCharacters 会停止；
• // 是另一条明确 Snippet，输入第二个 / 应优先展开空分式。

Enter/Tab 被其他扩展接管

1. 在 Keyboard Shortcuts 搜索 texleaf、tab、enter；
2. 运行 Developer: Toggle Keyboard Shortcuts Troubleshooting；
3. 确认 texleaf.matrixShortcuts=true；
4. 检查环境是否在 texleaf.matrixEnvironments；
5. 暂时停用 LaTeX Workshop 等扩展比较；
6. 注意 Tab 先处理活动 snippet tabstop，再执行列操作。

left/right 智能 Enter 只处理唯一、顶层、安全配对。遇到嵌套 pair、&、已有 \\、命令参数、注释或嵌套环境时回退普通行为是设计选择。

管理器问题

一直显示“正在载入”

• 先升级到 0.7.1；
• 运行 Developer: Reload Window；
• 打开 Developer: Toggle Developer Tools，查看 Webview CSP/脚本错误；
• 检查 Profile 是否允许扩展 globalStorage 写入；
• 暂停同步后重试，排除另一个窗口持续修改；
• 不要把旧版全局 JSONC 的 JavaScript/函数格式直接粘入结构化数据。

管理器的 ready 握手会重试，主机加载和消息有边界；正常库不应永久 busy。

保存提示 revision/并发冲突

这表示管理器载入后，另一个窗口、高级 JSONC、Settings Sync 或恢复操作修改了同一库。正确处理：

1. 复制尚未保存的重要草稿；
2. 选择重新载入当前磁盘/Profile 内容；
3. 重新应用变更；
4. 再保存。

不要通过反复点击保存绕过 CAS。冲突拒绝是在保护另一个窗口的修改。

批量替换结果不对

• 先检查选中的字段范围；
• 正则模式下 replacement 使用 JavaScript 字符串替换语义，但数据仍不可执行脚本；
• 关闭正则时，查找内容按字面量处理；
• 看预览中的 before/after 与数量；
• 应用后仍是草稿，可先撤销再保存；
• 大规模操作前先导出备份。

恢复默认后自定义丢失

恢复默认会明确替换当前工厂库，但成功前应创建原字节备份。到当前扩展宿主的 globalStorageUri/backups 中恢复，或从先前导出文件导入。不要从另一 Profile 猜路径；先确认 Stable/Insiders、本地/Remote 和 Profile。

模板不展开

四个模板要求：

• 已保存的 .tex；
• 单光标；
• 文档除空白和完整 trigger 外无其他内容；
• 自动展开需 autoSnippets=true，否则按 Tab。

若修改 trigger 后旧 trigger 仍生效：

• 确认管理器右上角已保存且无错误；
• 重新选择该模板检查值；
• 搜索是否另有同 trigger Snippet；
• Reload Window 后复试；
• 确认当前 Profile 与修改时相同。

article 模板参考文献样式应是 alpha。Beamer 中的 \theoremstyle{plain} 是定理样式，不是 bibliography style。

Settings Sync 问题

• Settings Sync 必须在 VS Code 账户中主动开启；
• 手工 VSIX 不会自动安装到另一设备；先安装相同 extension ID 的兼容版本；
• 同步检测不是实时，通常等窗口重新聚焦或下一轮约 15 秒检查；VS Code 云端传播另计；
• envelope 超过 256 KiB、库无效或 dirty 时暂停同步；
• Profile、Stable/Insiders、本地/Remote 可能是独立副本；
• 双方都改动时会提示冲突，不会自动选“最新时间”。

\cite{} 没有文献

检查：

• 当前工作区是否信任；
• .tex 是否已保存；
• texleaf.enabled、texleaf.zoteroCitations；
• 命令是否在 texleaf.citationCommands；
• 光标是否真的在必需大括号内，而不是可选参数或命令外；
• bibliographyFile 是否指向当前 workspace root 内的 .bib；
• .bib 是否存在未闭合外层条目或重复 key；
• 手动运行 TeXLeaf: 显示参考文献补全。

即使 Zotero 不可用，合法的已有 bibliography 条目仍应出现。

Zotero 没有候选或连接失败

1. 启动 Zotero，并等待主窗口完全加载；
2. 确认允许本机其他应用通信；
3. 默认端口 23119，Juris-M 常见 24119；
4. 检查 zoteroLibrary 名称，重名群组库改用数字 ID；
5. 运行 TeXLeaf: 刷新 Zotero 参考文献缓存；
6. 查看 Output 中是 connection、404、timeout、library-not-found、RPC 还是 invalid-response；
7. Better BibTeX 不可用时，确认 Zotero 官方 Local API 可用；
8. Flatpak/Snap/安全软件可能隔离回环连接。

不要把端口改成公网转发，也不要尝试配置远程主机；TeXLeaf 固定 127.0.0.1。

Remote/WSL/SSH/Container

127.0.0.1 指扩展宿主所在网络命名空间。确认 TeXLeaf 安装在本地 UI 一侧；若它只安装/运行在 Remote，则端口指远程机器/容器，本机 Zotero 不可达。Codespaces 浏览器环境不能假设访问桌面 Zotero。

更多边界见 文献与 Zotero#WSL、Remote-SSH、Dev-Container-与-Codespaces。

仍然出现 citation key 候选

先区分来源：

• abc/Text 类型普通文档单词：TeXLeaf 已为 [latex]/[tex] 默认设置 editor.wordBasedSuggestions=off；检查用户/工作区是否显式覆盖。
• Reference 类型、逐条来自 .bib 的 key：很可能是 LaTeX Workshop 自己的 citation provider，不是 TeXLeaf。

TeXLeaf 不能从 VS Code 合并后的列表中删除另一个扩展的候选。可让 LaTeX Workshop 改用标题标签：

{
  "latex-workshop.intellisense.citation.label": "title"
}

不要用 editor.suggest.showReferences=false，它会同时隐藏 TeXLeaf citation 和 \ref 等 Reference 补全。完整解释见 文献与 Zotero#与-LaTeX-Workshop-及其他补全共存。

Zotero 导入失败或重复

• 导出格式必须是 bibtex 或 biblatex；
• .bib 未闭合、重复 key 或 key 被不同文献占用时会停止；
• DOI/ISBN/标题/第一作者/年份不足会降低跨 key 去重能力；
• dirty bibliography 不自动保存是保护行为；
• 提交前当前 citation/文档版本改变会取消；
• Better BibTeX 返回多个条目或 key 不一致会拒绝；
• 查看 Output 的明确错误，不要手工重复点击导入多次。

Math Preview 不显示

检查：

• 当前是已保存 .tex，language ID 为 LaTeX/TeX；
• texleaf.mathPreview.enabled=true；
• presentation 是否是预期的 cursor/hover/both；
• 光标是否在完整或当前可安全识别的公式中；
• 是否位于注释、verb/verbatim、lstlisting、minted；
• 公式是否超过 maxSourceLength；
• 运行 TeXLeaf: 刷新 Math Preview；
• 查看 Output 中 MathJax render、timeout、macro 或 asset 错误。

只有空框或公式模糊

0.7.1 使用 Base64 data: URI 给 cursor decoration，避免 Windows MAX_PATH 造成生成了 SVG 却加载为空框。若仍为空：

• 确认不是旧 VSIX；
• 刷新预览并 Reload Window；
• 用默认深色/浅色主题比较；
• 查看开发者工具是否拒绝 data URI；
• 提供公式最小复现。

模糊/锯齿受 Chromium、系统 DPI、显示器、字体缩放和 window.zoomLevel 影响。尝试整数 zoom、默认主题和系统推荐缩放进行对照。TeXLeaf 公式本身是 SVG path，不建议用 Custom CSS 给所有 path 加 stroke。

预览遮挡、裁切或对齐

• 行内 auto 应位于活动源码行下方；起始行对齐 delimiter，后续行对齐首个非空白字符；
• 行间预览应对齐 opening delimiter；
• 上下无空白时，decoration 无法给正文预留真实高度，可能临时遮住相邻行；
• 超宽行间公式右端裁切是已知 API 边界，不应通过错误跳到第 0 列解决；
• 可降低 scale、切换 hover、添加空白行或显式选择 above/below；
• 对齐问题请同时提供 opening 行、锚点/光标行、Tab Size、字体、Zoom 和截图。

平台专项

Windows

• 确认安装目录、Profile 路径和 workspace 中的中文/空格没有被自定义脚本错误转义；
• Zotero 与 VS Code 应在同一桌面会话；
• 安全软件不要阻止回环；
• 旧空框问题优先确认版本，不要手工清整个用户数据目录。

macOS

• 运行时正式支持 macOS；快捷键使用 Cmd+Alt+L，其余 Tab/Enter/Shift+Enter/Escape 与 Windows/Linux 相同；
• 确认下载的 VSIX 未被浏览器自动解压；
• Zotero 必须是当前用户桌面会话中的本机应用；
• 若视觉定位或抗锯齿异常，报告 Retina/非 Retina、显示缩放、主题和 window.zoomLevel；
• 仓库中的固定视觉宿主/CDP 辅助脚本当前以 Windows CLI/窗口路径为主要自动化环境，不随 VSIX 发布；Release 前仍应在真实 macOS VS Code 上人工验收片段、引用、浅/深主题预览和快捷键。

Linux

• 检查 code CLI 是否在 PATH；
• Flatpak/Snap/AppImage 与系统 Zotero 可能有沙箱边界；
• Wayland/X11 和分数缩放会影响 Chromium 抗锯齿与 decoration 像素；
• 报告发行版、桌面环境、显示协议和缩放。

创建高质量 Issue

请提供：

• TeXLeaf、VS Code、操作系统版本；
• Local/WSL/SSH/Container/Codespaces 与扩展安装位置；
• Zotero 和 Better BibTeX 版本（文献问题）；
• 最小 .tex/.bib 片段，删除个人信息和未公开文献数据；
• 相关设置的用户/工作区/语言覆盖；
• 是否安装 LaTeX Workshop、Ultra Math Preview 或键位扩展；
• 从全新 Profile 是否可复现；
• Output → TeXLeaf 日志；
• UI 问题的深/浅主题截图、DPI/缩放/Zoom。

不要上传完整 Zotero 数据库、私人 .bib、访问凭据、系统环境变量或整个 VS Code 用户目录。

相关页面

• 配置参考
• 片段与模板
• Snippet 格式
• 文献与 Zotero
• Math Preview
• 开发与发布
• 首页