Files
MDHelper/docs/troubleshooting.md
T
2026-06-18 12:30:37 +08:00

126 lines
3.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# MDHelper 常见问题
## 右侧外部目录栏还显示
默认推荐使用网页内文档大纲,位置在正文右侧。若仍看到最右侧 Qt 目录栏,请检查:
1. 打开 `工具 - 设置`。
2. 勾选 `网页内大纲`。
3. 取消或禁用 `外部目录栏`。
4. 刷新当前文档。
当网页内大纲开启时,外部目录栏会自动隐藏。
## 文档大纲在正文左侧
0.2.0 当前布局应为正文在左、大纲在正文右侧。如果仍在左侧,说明正在运行旧 exe 或旧源码。请重新运行最新源码,或重新打包 exe。
## 每行文字太少或太多
打开 `工具 - 设置 - 纸张宽度`:
- 默认 `A4(x1)`:适合普通阅读。
- `A4 × 1.25` / `A4 × 1.5`:适合宽屏。
- `A4 × 1.75` / `A4 × 2`:适合代码、宽表格和技术文档。
纸张宽度只改变正文最大宽度,不改变字号。
## 滚动不够流畅
可尝试:
- 使用网页内大纲和网页内进度条。
- 关闭外部目录栏。
- 将鼠标滚轮速度保持在 `1.0` 附近。
- 对超大代码文件,避免同时启用过多文件类型。
- Mermaid、公式、大图片和超长代码块很多的文档会更依赖 WebEngine 渲染性能。
## 文件夹很大时卡顿
建议:
- 默认只展示 Markdown / 网页文件。
- 只在需要时启用 Python 或 C/C++。
- 避免把构建目录、依赖目录、虚拟环境目录作为阅读根目录。
- 使用左侧搜索定位目标文件。
MDHelper 会跳过超大代码文件的全文索引和部分高亮处理,以减少卡顿。
## 文件被外部修改后没有刷新
检查 `工具 - 设置 - 自动刷新`:
- 推荐选择 `当前文档、资源和目录`。
- 推荐刷新延迟为 `标准(1 秒)`。
- 若关闭自动刷新,需要手动点击刷新按钮或按 `F5`。
MDHelper 读取文档时不会锁定文件,外部编辑器仍可保存。
## 图片或媒体打不开
检查:
- Markdown 中的相对路径是否正确。
- 文件是否仍在原位置。
- 文件名大小写是否一致。
- 视频格式是否被 Qt 内置播放器支持。
对不支持的媒体格式,可选择用系统默认程序打开,也可以记住指定播放器。
## DOCX 导出失败
检查:
- 是否安装 pandoc。
- 是否安装 python-docx。
- 当前文档路径和输出目录是否可写。
- 文档中引用的图片路径是否存在。
如果 pandoc 不可用,可切换到 python-docx 相关实现;复杂 Markdown 的 DOCX 版式通常 pandoc 更稳定。
## PDF 导出失败
检查:
- 当前文档是否能正常阅读。
- 输出路径是否可写。
- 文件名是否包含系统不允许的字符。
- WebEngine 是否已完成页面加载。
可先导出 HTML,确认内容渲染正常,再导出 PDF。
## 代码文件不显示
打开 `工具 - 设置 - 展示文件类型`,勾选需要的类型:
- Python
- C / C++
设置后文件树、搜索索引和自动刷新监听会随之更新。
## 设置后没有变化
多数设置会立即刷新当前文档。若仍未变化:
1. 按 `F5` 刷新。
2. 切换标签页再切回。
3. 关闭旧 exe,重新启动最新版本。
## 打包版提示缺少 PySide6
说明 PyInstaller 打包时没有正确带上 PySide6 或 WebEngine 资源。请使用项目根目录下的 `MDHelper.spec` 打包:
```powershell
.\mdhelper_env\Scripts\python.exe -m PyInstaller .\MDHelper.spec --noconfirm --clean
```
打包后执行:
```powershell
.\dist\MDHelper.exe --check --project-root .
```
## 如何定位日志
MDHelper 会把日志写到用户可写目录。若启动或打开文档异常,优先查看最近的运行日志,并把错误堆栈和打开的文件路径一起记录下来。