疑難排解

快速查找

常見問題與對應的修復位置：

症狀	可能原因	查找位置
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 會從工作區資料夾及其中直接包含、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（反向搜尋歷史）；而 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 組合上（回報的案例是搭配 KDE Plasma 6 的 Arch，#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 只要求不被 App Nap 休眠。