❓ 07. 常見問題與故障排查 (Troubleshooting)

彙總用戶日常使用中最容易遇到的問題與快速排障手冊。
如果您在使用 FlashNote 過程中遇到任何異常，請參考下方對應的解決方案。

📑 本篇大綱

1. 筆記儲存後找不到？
2. 圖片無法顯示？
3. 同步一直未完成（卡在同步中）？
4. 部落格發布失敗？
5. AI 服務連接失敗？
6. 瀏覽器資料清理後如何還原？
7. 擴充功能安裝提示權限敏感（瀏覽記錄、剪貼簿），是否安全？
8. 如何反饋問題與回報 Bug？

1. 筆記儲存後找不到？

排查步驟：

1. 檢查分類過濾與標籤：
   • 檢查左側欄是否正選中了某個具體標籤或分類資料夾，點擊頂部的 「全部速記」 即可展示所有筆記；
2. 檢查搜尋關鍵字：
   • 查看頂部搜尋欄是否殘留有之前的搜尋詞，清空搜尋框即可重新載入全量列表；
3. 檢查「最近刪除」回收站：
   • 檢查是否在手誤時點擊了刪除操作，進入左下角設定旁的「最近刪除」查看是否存在並支援一鍵還原；
4. 資料庫索引刷新：
   • 極少數情況下瀏覽器多標籤切換可能導致頁面視圖未即時派發更新事件，按下 Ctrl/Cmd + R 刷新側邊欄面板即可重新拉取。

2. 圖片無法顯示？

排查步驟：

1. 剪藏圖片的離線快取狀態：
   • FlashNote 在網頁剪藏時會抓取圖片存入本地 IndexedDB。若剪藏時網路瞬時斷開，原圖可能未能成功寫入快取；
   • 重新打開原網頁，再次對該圖執行剪藏即可；
2. 外部外鏈圖片防盜鏈：
   • 若直接貼上了帶有防盜鏈（Referer 限制）的外部圖片 URL，瀏覽器可能會攔截該圖片的請求頭；
   • 建議在網頁中先右鍵「複製圖片」（直接獲取圖像二進位串流），再在 FlashNote 中按下 Ctrl/Cmd + V 貼上，觸發本地化沙盒儲存；
3. 瀏覽器儲存配額限制：
   • 打開「設定」 -> 「資料與備份」，查看磁碟空間占用是否已達到上限。

3. 同步一直未完成（卡在同步中）？

排查步驟：

1. 檢查網路連通性：
   • 檢查當前網路是否能正常訪問您所綁定的雲端/WebDAV 伺服器；
2. 憑證失效與過期：
   • 某些雲端提供商的 Access Token 會定期過期。進入「設定」 -> 「網盤同步」，重新點擊「驗證授權」；
3. 解除併發死鎖：
   • 若同步指示燈長時間處於旋轉狀態，點擊同步指示燈選擇 「強制重設同步鎖」，系統將安全重設當前鎖狀態並重新排隊。

4. 部落格發布失敗？

排查步驟：

1. 發布前三態門禁狀態檢查：
   • 檢查頂部狀態欄是否標紅顯示 Blocked (阻斷)；
   • 點擊 Blocked 標籤查看具體報錯：
     • Slug 衝突：當前文章設定的英文別名與該目錄下其他文章重複，修改當前 Slug 即可解決；
     • 缺少必要 FrontMatter 欄位：如未填寫標題或必填的發布時間；
2. 本地目錄授權過期：
   • 瀏覽器每次冷啟動後，可能需要對 File System Access 目錄重新授予寫入權限。點擊提示彈窗中的「允許重新訪問」即可。

5. AI 服務連接失敗？

排查步驟：

1. 觸發 429 頻控或配額用盡：
   • 平台返回 429 Too Many Requests。若配置了「備用模型 (Fallback Model)」，系統會自動進行故障無感切換；若未配置備用模型，請稍等 1~2 分鐘再試，或更換自己的專屬 API Key；
2. API 密鑰與 Endpoint 格式：
   • 確認輸入的 API 基礎位址末尾是否有多餘的斜線或缺失 /v1；
   • 確保 API Key 沒有前後多餘的空格；
3. 跨域攔截 (CORS)：
   • 若使用自建的反向代理服務，請確保反向代理伺服器配置了 Access-Control-Allow-Origin: * 響應頭。

6. 瀏覽器資料清理後如何還原？

Chrome 等瀏覽器在執行「清理瀏覽資料（勾選 Cookies 及其他網站資料）」時，可能會清除本地 IndexedDB。

還原與預防措施：

• 從日常匯出的 ZIP / JSON 備份一鍵還原：
  • 打開 FlashNote 「設定」 -> 「資料與備份」 -> 「還原備份」，上傳最近的備份檔案，秒級無損還原所有筆記與離線圖片；
• 配置雲端自動差量同步：
  • 只要開啟了 WebDAV 或雲端差量同步，即便本地資料庫被意外清理，重新綁定同步憑證後，全量筆記將自動從雲端重新拉取；
• 重要防範建議：
  • 清理瀏覽器快取時，建議在進階清理選項中取消勾選「Cookie 與網站資料」，以長期保護所有擴充功能的離線沙盒資料。

7. 擴充功能安裝提示權限敏感（如「讀取瀏覽記錄」、「修改剪貼簿」），是否安全？

許多使用者在從應用程式商店安裝或更新 FlashNote 時，看到瀏覽器彈出如下權限提示可能會產生疑慮：

為什麼瀏覽器會提示這些權限？

Chromium / Chrome 等瀏覽器的權限警告機制粒度較為粗放，會將許多底層開發 API 統一映射為最寬泛的強警告文字。FlashNote 請求這些權限的真實動機與技術用途如下：

1. 「讀取您的瀏覽記錄 (Read your browsing history)」
   • 底層 API：tabs 權限。
   • 真實用途：僅用於一鍵網頁剪藏 (Web Clipper) 功能。當您在瀏覽某網頁並點擊 FlashNote 懸浮球/快捷鍵進行速記時，擴充功能需要獲取當前分頁的頁面標題與網頁 URL，以便自動在筆記底部附上來源連結，省去手動複製貼上的繁瑣操作。
   • 安全邊界：我們絕不掃描、遍歷或讀取您的歷史瀏覽記錄。該權限僅在您主動點擊剪藏動作的那一刻，讀取當前這一個活動分頁的基礎位址與標題。
2. 「修改您複製和貼上的資料 (Modify data you copy and paste)」
   • 底層 API：clipboardRead 與 clipboardWrite 權限。
   • 真實用途：用於智慧格式化複製與貼上。
     • 匯出/分享：當您點擊「一鍵複製 Markdown」、「複製為富文本/圖片」時，擴充功能需要擁有向系統剪貼簿寫入內容的權限；
     • 快速速記：當您使用快捷鍵捕獲當前剪貼簿文字快速生成卡片時，擴充功能需要讀取您剛剛複製的內容。
   • 安全邊界：絕無背景常駐監聽。FlashNote 僅在您主動點擊複製按鈕或觸發速記熱鍵時執行單次讀取/寫入，絕不會在背景竊聽或記錄您的敏感剪貼簿資訊（如帳號密碼、驗證碼等）。
3. 「顯示通知 (Display notifications)」
   • 真實用途：在執行離線多端同步完成、大檔案/圖片匯出成功、或定時速記待辦到期提醒時，向您展示非侵入式的輕量桌面氣泡通知。

8. 如何反饋問題與回報 Bug？

如果上述指南未能解決您的問題，或者您發現了軟體缺陷與功能建議，歡迎隨時聯繫我們：

• 📧 官方技術支援信箱：[email protected]

• 💬 GitHub 交流討論區：FlashNote 官方討論區

• 🐞 提交 Bug 時建議附帶的資訊：

  1. 瀏覽器名稱與版本號（例如 Chrome 126.0 / macOS）；
  2. 遇到問題時的操作步驟簡述；
  3. 主控台是否有標紅的錯誤日誌截圖（請勿直接按 F12，需在 FlashNote 擴充功能介面任意位置按右鍵點擊並選擇 Inspect (檢查)，然後在彈出的開發者工具中切換至 Console (主控台) 標籤頁）：