故障排除

快速查找

常见问题及其修复参考：

症状	可能的原因	查看位置
MCP 客户端无法连接	过期的端口文件或 VMark 未运行	MCP 服务器连接问题
文件无法打开或显示乱码	非 UTF-8 编码或隔离属性	文件无法打开
AI 精灵卡住或无返回	提供商未正确配置或 CLI 不在 PATH 中	AI 精灵无响应
键盘快捷键无效	在设置中被重新分配或被系统覆盖	键盘快捷键不起作用
大文件下编辑器变慢	每标签页内存 + 1 万行以上输入延迟	编辑器性能
切换语言后菜单仍是英文	菜单在启动时重建	切换语言后菜单栏仍显示英文
PDF 导出不完整	图片路径或写入权限	导出/打印问题
Windows 启动缓慢	WebView2 + 杀毒软件扫描	应用在 Windows 上启动缓慢
Cmd + R / Ctrl + R 没有反应	重新加载被有意禁用	重新加载被禁用
双击文件后在正在运行的 VMark 中打开了它	Windows 和 Linux 上的单实例转发	Windows 和 Linux 上同一时间只运行一个 VMark
Linux 上窗口空白	WebKitGTK DMABUF 渲染器	Linux 上窗口空白
在 macOS 上直引号和 -- 保持原样	系统智能替换已对 VMark 关闭	macOS 上的智能引号和破折号
活动监视器中 VMark 从不"小憩"	已禁用 App Nap，以便 AI 助手持续工作	VMark 在后台保持唤醒（App Nap）
打开最近的工作区时弹出文件夹对话框，或错误信息提到 forbidden path	该文件夹不在 VMark 可读取的范围内	文件夹访问与 forbidden path 错误

未列出的问题请见 报告 Bug。

日志文件

VMark 会写入日志文件以帮助诊断问题。日志包含来自 Rust 后端和前端的警告与错误信息。

日志文件位置

平台	路径
macOS	~/Library/Logs/app.vmark/
Windows	%LOCALAPPDATA%\app.vmark\logs\
Linux	~/.local/share/app.vmark/logs/

日志级别

级别	记录内容	生产环境	开发环境
Error	失败、崩溃	是	是
Warn	可恢复的问题、降级处理	是	是
Info	关键节点、状态变化	是	是
Debug	详细跟踪信息	否	是

日志轮转

• 最大文件大小：5 MB
• 轮转策略：保留一个历史日志文件
• 旧日志会被自动替换

报告 Bug

报告 Bug 时，请包含以下信息：

1. VMark 版本 — 显示在导航栏徽章或"关于"对话框中
2. 操作系统 — macOS 版本、Windows 版本号或 Linux 发行版
3. 复现步骤 — 问题发生前你做了什么操作
4. 日志文件 — 附上或粘贴相关的日志条目

日志条目带有时间戳并按模块标记（例如 [HotExit]、[MCP Bridge]、[Export]），便于查找相关内容。

查找相关日志

1. 根据上表打开日志目录
2. 打开最新的 .log 文件
3. 搜索问题发生时间附近的 ERROR 或 WARN 条目
4. 复制相关行并附在你的 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 文件。（通过字节顺序标记）标明为 UTF-16 或 UTF-32 的文件会在打开时被拒绝，并弹出提示：“路径 的编码是 编码。VMark 只能打开 UTF-8 文件，请先在其他编辑器中另存为 UTF-8，再重新打开。”其他旧式编码（GB2312、Shift-JIS）没有这种标记；它们可以打开，但可能显示为乱码——请先将其转换为 UTF-8。
• 以字节顺序标记开头的 UTF-8 文件会保留它：VMark 在打开和保存时都会保留 BOM。
• 如果文件被其他进程锁定（如同步客户端或备份工具），请关闭该进程后重试。
• macOS：VMark 运行时双击下载的文件没有反应。 某些应用保存的文件带有下载隔离属性（com.apple.quarantine），而 macOS 可能会悄悄丢弃在已运行的应用中打开此类文件的请求。当你打开工作区时，VMark 会移除工作区文件夹以及其中可直接打开的文件上的该属性（不会触及子文件夹）——这由 设置 → 高级 → macOS 下的 打开工作区时清除下载隔离标记 设置控制，默认开启。对于其他文件，请使用 文件 → 打开文件...，或在终端中运行 xattr -d com.apple.quarantine <file>。

文件夹访问与 forbidden path 错误

在你的主文件夹和已挂载的卷之外——在 Windows 上则是 C:\ 到 F:\ 驱动器之外——VMark 只读取你已授予其访问权限的内容；参见 VMark 能读取磁盘上的哪些内容。

• 选择最近的工作区时弹出了文件夹对话框。 VMark 无法确认你之前选择过该文件夹，也没有其他途径可以读取那里。对话框会在该文件夹处打开：点击打开即可确认，此后 VMark 会记住它。如果取消，则不会打开任何内容。
• AI 助手请求打开文件夹时需要多一步。 在你批准请求后，VMark 会显示同一个对话框；在其中选择该文件夹，然后让助手重试。
• 错误信息中提到 forbidden path，或者图片不显示。 该文件位于 VMark 可读取的所有位置之外——通常是你单独打开的文档旁边的图片。使用**文件 → 打开工作区...**打开文档所在的文件夹，即可让 VMark 访问整个文件夹。

编辑器性能

在文件非常大或打开了很多标签页时，编辑器可能会变慢。

• 关闭未使用的标签页以释放内存——每个打开的标签页都维护其独立的编辑器状态。
• 非常大的文档（超过 10,000 行）可能导致输入延迟。考虑将其拆分为更小的文件。
• 如不需要，请禁用专注模式和打字机模式，因为它们会增加额外的渲染开销。

AI 精灵无响应

AI 精灵需要已配置的 AI 提供商才能工作。

• 打开设置，验证是否配置了 AI 提供商（如 Ollama、OpenAI、Anthropic）并填写了有效的模型名称。
• 提供商的 CLI 必须在你的 PATH 中可用。在 macOS 上，GUI 应用的 PATH 是最小化的——如果 CLI 是通过 Homebrew 安装的，请确保你的 Shell 配置文件导出了正确的路径。
• 检查模型名称是否有拼写错误。不正确的模型名称会静默失败或返回错误。

重新加载被禁用

Cmd + R、Ctrl + R 和 Ctrl + Shift + R 不会有任何反应，这是有意为之。重新加载 webview 会丢弃所有已打开的编辑器、它们的撤销历史以及所有未保存的状态，因此 VMark 会拦截这些快捷键、页面卸载路径以及 webview 自带的右键菜单。有两个例外：当集成终端获得焦点时，Ctrl + R 会传递给 Shell（反向搜索历史，reverse-i-search）；F5 永远不会被拦截，因为它是源码预览的快捷键。开发版本只会对未保存的文档发出警告。

Windows 和 Linux 上同一时间只运行一个 VMark

双击文件，或从启动器再次启动 VMark 时，文件会交给已经在运行的 VMark，并把一个窗口调到前台，而不会启动第二个副本。第二个进程会与第一个共享应用数据、会话和窗口存储，两者会互相覆盖对方的状态——这正是 #1330 中数据丢失的原因。macOS 一直通过操作系统实现这种行为。开发版本（tauri dev）使用自己的标识符，因此被视为另一个应用。

在 Windows 上，如果已经在运行的 VMark 停止响应、无法再接收转交，再次启动不会在它旁边启动第二个副本，而是显示一条提示：请打开任务管理器，结束所有 VMark 进程，然后重新启动 VMark（#1527）。

在 Linux 上，这依赖 D-Bus 会话总线。如果会话中没有可用的 DBUS_SESSION_BUS_ADDRESS，VMark 仍会启动，但没有这层保护——再次启动会运行第二个副本，带来上述风险——日志中会记录该保护已关闭。请从桌面会话中启动，或从已设置该变量的 Shell 中启动。

Linux 上窗口空白

在某些 AMD / Mesa / WebKitGTK 组合上（报告的案例是 Arch 搭配 KDE Plasma 6，#1058），WebKitGTK 的 DMABUF 渲染器会失败，内容区域一直空白。VMark 会在 webview 启动前设置 WEBKIT_DISABLE_DMABUF_RENDERER=1，从而避免这种情况。如果你想恢复 DMABUF 渲染器，请使用 WEBKIT_DISABLE_DMABUF_RENDERER=0 启动——VMark 只在你没有设置该变量时才会设置它。

开启中文输入法时快捷键会输入字符

已修复。开启中文标点后，输入法会改写标点按键——反引号键输出 ·，方括号输出 【】——并且它会在应用得知按键被按下之前就提交该字符。因此 Ctrl + ` 过去在切换终端的同时还会在文档中留下一个多余的 ·，把一个干净的文件标记为已编辑。

VMark 现在拦截的是插入本身，而不是按键，因此命令组合键不会输入任何内容。正常的中文输入、死键（Option + e）以及欧洲键盘上的 AltGr 字符都不受影响——只有在按住 Ctrl 或 Cmd 时到达的插入才会被拒绝，而 VMark 没有任何组合键的含义是"输入这个字符"。

如果你仍然看到快捷键留下了多余的字符，欢迎报告问题，并附上输入法名称和确切的组合键。

macOS 上的智能引号和破折号

即使你的 Mac 开启了使用智能引号和破折号，在 VMark 中输入 -- 或 " 也会保持原样。否则系统会在编辑器底层改写文本——Mermaid 代码块中的 --> 会变成 —>——因此 VMark 仅对自身进程关闭自动破折号、引号和句号替换。其他应用不受影响，输入法和你自己的文本替换也不受影响。如需在 VMark 中使用印刷体引号，请使用中日韩格式化工具的智能引号规则或引号样式切换（Shift + Mod + '）。

VMark 在后台保持唤醒（App Nap）

在 macOS 上，VMark 在运行期间会一直退出 App Nap，因此即使窗口被隐藏，活动监视器也会显示它从不小憩。App Nap 会冻结 webview——连同所有 AI 助手（MCP）请求——直到你把某个窗口调到前台；保持唤醒让助手在你使用其他应用时也能继续工作。系统空闲时仍可能进入睡眠；VMark 只是请求不被小憩。