故障排除
快速查找
常见问题及其修复参考：
| 症状 | 可能的原因 | 查看位置 |
|---|---|---|
| MCP 客户端无法连接 | 过期的端口文件或 VMark 未运行 | MCP 服务器连接问题 |
| 文件无法打开或显示乱码 | 非 UTF-8 编码或隔离属性 | 文件无法打开 |
| AI 精灵卡住或无返回 | 提供商未正确配置或 CLI 不在 PATH 中 | AI 精灵无响应 |
| 键盘快捷键无效 | 在设置中被重新分配或被系统覆盖 | 键盘快捷键不起作用 |
| 大文件下编辑器变慢 | 每标签页内存 + 1 万行以上输入延迟 | 编辑器性能 |
| 切换语言后菜单仍是英文 | 菜单在启动时重建 | 切换语言后菜单栏仍显示英文 |
| PDF 导出不完整 | 图片路径或写入权限 | 导出/打印问题 |
| Windows 启动缓慢 | WebView2 + 杀毒软件扫描 | 应用在 Windows 上启动缓慢 |
未列出的问题请见 报告 Bug。
日志文件
VMark 会写入日志文件以帮助诊断问题。日志包含来自 Rust 后端和前端的警告与错误信息。
日志文件位置
| 平台 | 路径 |
|---|---|
| macOS | ~/Library/Logs/app.vmark/ |
| Windows | %APPDATA%\app.vmark\logs\ |
| Linux | ~/.local/share/app.vmark/logs/ |
日志级别
| 级别 | 记录内容 | 生产环境 | 开发环境 |
|---|---|---|---|
| Error | 失败、崩溃 | 是 | 是 |
| Warn | 可恢复的问题、降级处理 | 是 | 是 |
| Info | 关键节点、状态变化 | 是 | 是 |
| Debug | 详细跟踪信息 | 否 | 是 |
日志轮转
- 最大文件大小：5 MB
- 轮转策略：保留一个历史日志文件
- 旧日志会被自动替换
报告 Bug
报告 Bug 时，请包含以下信息：
- VMark 版本 — 显示在导航栏徽章或"关于"对话框中
- 操作系统 — macOS 版本、Windows 版本号或 Linux 发行版
- 复现步骤 — 问题发生前你做了什么操作
- 日志文件 — 附上或粘贴相关的日志条目
日志条目带有时间戳并按模块标记（例如 [HotExit]、[MCP Bridge]、[Export]），便于查找相关内容。
查找相关日志
- 根据上表打开日志目录
- 打开最新的
.log文件 - 搜索问题发生时间附近的
ERROR或WARN条目 - 复制相关行并附在你的 Bug 报告中
常见问题
应用在 Windows 上启动缓慢
VMark 针对 macOS 进行了优化。在 Windows 上，由于 WebView2 初始化，启动可能较慢。请确保：
- WebView2 Runtime 已更新到最新版本
- 杀毒软件没有对应用数据目录进行实时扫描
切换语言后菜单栏仍显示英文
如果在设置中切换语言后菜单栏仍然显示英文，请重启 VMark。菜单会在下次启动时使用已保存的语言重新构建。
终端不接受中日韩标点符号
已在 v0.6.5+ 中修复，请更新到最新版本。
MCP 服务器连接问题
MCP 服务器可能无法启动，或客户端无法连接。
- 确保 VMark 正在运行——MCP 服务器仅在应用打开时启动。
- 检查是否有其他进程占用了相同端口。MCP 服务器会写入端口文件供客户端发现；前一个会话留下的过期端口文件可能导致冲突。重启 VMark 以重新生成。
- 查看日志文件中的
[MCP Bridge]条目以识别连接错误。
键盘快捷键不起作用
如果快捷键与其他绑定冲突或已被自定义，可能表现为无响应。
- 打开设置（
Mod + ,）并导航到 快捷键 标签页，检查快捷键是否被重新分配。 - 查找重复绑定——如果两个操作共享同一组合键，只有一个会触发。
- 在 macOS 上，某些快捷键可能与系统级绑定冲突（如 Mission Control、Spotlight）。请检查 系统设置 > 键盘 > 键盘快捷键。
导出/打印问题
PDF 导出可能卡住或产生不完整的输出。
- 如果导出中缺少图片，请验证图片路径相对于文档且文件存在于磁盘上。绝对 URL 和远程图片应该可以访问。
- 检查输出目录的文件权限——VMark 需要写入权限才能保存导出的文件。
- 对于大型文档，导出可能需要更长时间。如果看起来卡住了，请检查日志文件中的
[Export]条目。
文件无法打开
VMark 可能拒绝打开文件或显示乱码内容。
- 验证文件对你的用户账户有读取权限。
- VMark 期望 UTF-8 编码的 Markdown。其他编码的文件（如 GB2312、Shift-JIS）可能无法正确显示——请先将其转换为 UTF-8。
- 如果文件被其他进程锁定（如同步客户端或备份工具），请关闭该进程后重试。
编辑器性能
在文件非常大或打开了很多标签页时，编辑器可能会变慢。
- 关闭未使用的标签页以释放内存——每个打开的标签页都维护其独立的编辑器状态。
- 非常大的文档（超过 10,000 行）可能导致输入延迟。考虑将其拆分为更小的文件。
- 如不需要，请禁用专注模式和打字机模式，因为它们会增加额外的渲染开销。
AI 精灵无响应
AI 精灵需要已配置的 AI 提供商才能工作。
- 打开设置，验证是否配置了 AI 提供商（如 Ollama、OpenAI、Anthropic）并填写了有效的模型名称。
- 提供商的 CLI 必须在你的 PATH 中可用。在 macOS 上，GUI 应用的 PATH 是最小化的——如果 CLI 是通过 Homebrew 安装的，请确保你的 Shell 配置文件导出了正确的路径。
- 检查模型名称是否有拼写错误。不正确的模型名称会静默失败或返回错误。