流光笔记
首页

❓ 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 时，看到浏览器弹出如下权限提示可能会产生顾虑：

FlashNote 扩展权限声明

Important

郑重承诺：FlashNote 绝对不会窃取、监视或上传您的任何个人数据与浏览隐私！
FlashNote 采用严格的 “本地优先 (Local-First)” 离线沙箱架构。您的所有速记、图片与文档默认均存储在您当前设备的浏览器本地数据库（IndexedDB）中，绝无任何数据分析埋点或偷传行为。

为什么浏览器会提示这些权限？

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 (控制台) 标签页）：

    右键选择 Inspect 检查 切换至 Console 查看错误日志

Tip

返回知识库主目录：