跳转到内容
SpaceKnifeSpaceKnife 文档

故障排除

先找到和你看到的现象对应的小节。这里都解决不了时，带上第一节收集到的信息报告问题。

收集信息

Section titled “收集信息”

  • 日志面板：Ctrl+J（macOS 上 ⌘+J），或点击状态栏最左边一项。「日志」列出本次会话的事件：无法访问的文件夹、改用其他方式、失败的操作等；点「N 条警告」只看警告和错误。「扫描统计」显示当前标签的扫描：扫描方式、状态、开始、结束、耗时、文件 / 文件夹、已扫描合计、未知空间、无法访问的文件夹数和平均吞吐。

  • 日志文件：SpaceKnife 数据文件夹下 logs 里的 spaceknife.log。文件满 10 MB 时换新文件，保留之前的 5 个。

    系统 日志文件夹
    Windows %LOCALAPPDATA%\SpaceKnife\logs
    Linux ~/.local/share/SpaceKnife/logs
    macOS ~/Library/Application Support/SpaceKnife/logs

    「设置 › 高级 › 文件与诊断 › 日志文件夹 › 打开」无论它在哪里都能打开（便携版和 SPACEKNIFE_HOME 会改变位置，见数据位置与便携模式）。

  • 更详细的日志：把「设置 › 高级 › 日志 › 日志文件级别」改成「调试」，重现问题，再改回「信息」。

  • 「复制诊断信息」（「设置 › 高级 › 文件与诊断」）：复制界面和后端的版本、平台、后端的能力清单，以及设置文件和日志文件夹的路径。

  • 命令行：spaceknife-backend version 输出各部分的版本；其中的 native none 表示原生扩展没有加载（见命令行）。

首次启动

Section titled “首次启动”

Windows：SmartScreen 提示「未知发布者」

Section titled “Windows：SmartScreen 提示「未知发布者」”

安装包和应用还没有代码签名，所以第一次运行时 SmartScreen 会警告。点「更多信息」，再点「仍要运行」。每个版本都附带 SHA256SUMS.txt，可以用它核对下载的文件。

Windows 便携版：第一次启动慢，或者什么都存不下来

Section titled “Windows 便携版：第一次启动慢，或者什么都存不下来”
  • 解压后第一次启动会慢几秒，Windows 要先检查这些新文件。
  • 解压到你有写权限的文件夹。放在 C:\Program Files 之类的位置时，便携版写不了旁边的 data 文件夹。

macOS：提示无法验证 SpaceKnife

Section titled “macOS：提示无法验证 SpaceKnife”

macOS 版还没有经过苹果公证，第一次打开会被拦下，需要放行一次：

  1. 打开 SpaceKnife，系统提示无法验证它时点「完成」。
  2. 打开「系统设置 › 隐私与安全性」，往下找到 SpaceKnife 已被阻止的提示，点「仍要打开」，再点一次「仍要打开」并输入密码。

之后就能正常打开；安装新版本后需要再放行一次。macOS 14 上也可以在「应用程序」里右键 SpaceKnife 选「打开」。在终端里这样做效果相同：

终端窗口
xattr -dr com.apple.quarantine /Applications/SpaceKnife.app

Linux：AppImage 打不开

Section titled “Linux：AppImage 打不开”
  • AppImage 需要 FUSE 2（Ubuntu 22.04 上是 libfuse2）。没有时用 ./SpaceKnife-<版本>-x86_64.AppImage --appimage-extract-and-run 运行，或者改用不需要 FUSE 的 deb、rpm 或便携版 tar.gz。
  • 在限制非特权用户命名空间的发行版上（Ubuntu 23.10 起的 AppArmor 规则），AppImage 和便携版 tar.gz 可能启动不了，因为其中 Chromium 的沙箱程序没有 setuid。加 --no-sandbox 启动。Ubuntu 22.04 和 RHEL 9 不受影响。

「后端没有启动」

Section titled “「后端没有启动」”

窗口出现了，但被一段提示盖住，状态栏显示「后端不可用」。标题下面写着原因：「后端 30 秒内没有就绪」「后端启动失败（退出码 N）」或「后端已退出（退出码 N）」。

  • 重新打开 SpaceKnife。再次出现时，在终端里单独运行后端：spaceknife-backend version（位置见命令行）。那里的报错就是需要报告的内容。
  • 在 Linux 和 macOS 上，从终端启动 SpaceKnife 可以看到后端自己的输出，每行以 [backend] 开头。

权限

Section titled “权限”

Windows 的管理员授权

Section titled “Windows 的管理员授权”

MFT 快速扫描需要管理员权限。SpaceKnife 本身从不提权：它启动一个小的只读扫描助手，只有助手请求授权（UAC 提示）。详见扫描速度与磁盘负载。

  • 拒绝了授权：扫描继续以逐目录的硬扫描进行，「扫描详情」里会说明原因。
  • 过一会儿又来问：助手空闲 10 分钟后退出，之后的快速扫描会启动一个新的助手。
  • 永远不想看到提示：关掉「设置 › 扫描与性能 › 扫描方式 › 需要时请求管理员权限」，或把「默认扫描方式」设为「硬扫描」。
  • 没看到提示，扫描停在「正在等待管理员授权…」：去任务栏找 UAC 提示。「停止」可以取消这次扫描。
  • 「仅当前用户」安装时，助手从你的账户可写的文件夹启动。介意的话请选「所有用户」安装（装到 Program Files）。

完全磁盘访问权限

Section titled “完全磁盘访问权限”

macOS 上没有「完全磁盘访问权限」时，系统会为桌面、文稿、下载、iCloud 云盘和其他云盘、照片图库以及其他应用的数据分别询问权限，扫描时会一个接一个弹窗；邮件、信息等位置则完全读不到，计入未知空间。

扫描这些位置之前，SpaceKnife 会弹出「让 SpaceKnife 一次读到全部文件」：

  • 「打开系统设置」：在「完全磁盘访问权限」的列表里打开 SpaceKnife 的开关（没有就点 + 添加），再按提示重新打开 SpaceKnife。
  • 「跳过受保护的位置」：不弹窗，这些位置显示为无法访问。
  • 「照常扫描，逐个询问」：让 macOS 为每个位置分别询问。

勾选「记住「跳过」或「逐个询问」的选择」后不再询问；之后可以在「设置 › 扫描与性能 › 扫描范围 › 受保护的位置」里修改（「扫描前询问」「跳过，不弹窗」「照常访问」）。

无法访问与未知空间

Section titled “无法访问与未知空间”

未知空间 = 系统报告的已用空间 − 扫描找到的全部内容。只有扫描整个卷时才有，显示为灰色斜纹块，按 U 显示或隐藏。它通常由扫描无权读取的文件夹和系统保留的区域组成。

  • 读不了的文件夹会列在「扫描详情」里（「N 个文件夹无法访问」，并给出一个例子），日志面板里也有（「无法访问 …：拒绝访问，已计入未知空间」）。
  • Windows：MFT 快速扫描读取整个卷，留下的未知空间比硬扫描少得多。
  • macOS：给 SpaceKnife 完全磁盘访问权限（见上文）。
  • Linux：SpaceKnife 用你自己的权限扫描。想看系统文件夹里面，用命令行加 sudo 扫描。
  • 日志里的警告太多？关掉「设置 › 常规 › 日志 › 记录扫描警告」：无法访问的文件夹照样计数，只是不再逐条列出。「有新事件时自动打开日志面板」控制面板会不会自己弹出来。

扫描好像卡住了或很慢

Section titled “扫描好像卡住了或很慢”

按顺序检查：

  1. 暂停了吗？ 状态栏显示「已暂停」，进度条显示「磁盘读取已暂停，可随时继续」。点「继续」。
  2. 在让路吗？ 「扫描详情」显示「其他程序正在大量读写这块磁盘，扫描已让路（最低进度）」，说明有别的程序在大量读写这块盘。可以等一等，或在「磁盘负载上限」里选「极速」，立即生效；关掉「整盘繁忙时让路」则从下一次扫描起生效。
  3. 用的是「空闲」档？ 「空闲」档只在磁盘没有别的活动时读取。磁盘忙时换个档位，立即生效。
  4. 在等提示框？ Windows 上是管理员授权（「正在等待管理员授权…」），macOS 上是受保护文件夹的授权提示。回应它即可。
  5. 位置本身就慢？ 网络盘、机械硬盘、U 盘和存储卡同时只读很少几批；从 WSL 访问的 Windows 盘非常慢。见扫描速度与磁盘负载。
  6. 快结束时百分比变成「…」？ 这个位置没有以前的快照时，进度按卷的已用空间估算，到 95% 就不再计算，因为这个总数只是近似值。扫描仍在进行，项目数还在增长。

想知道扫描在等什么，扫描结束后看日志文件里的耗时分解（怎么看）。停止的硬扫描之后可以用状态栏的「继续扫描」接着扫，只读还没读过的文件夹。

内存警告

Section titled “内存警告”

日志面板显示「后端内存占用异常：N GB（扫描数据约 N GB），诊断信息已写入日志文件」。

后端每 15 秒比较一次自己的内存和打开的扫描所需的量。只有在把释放出来的内存还给系统之后，仍然明显超出（扫描数据的两倍加 1.5 GB，再加上最近一小时内关掉的最大那次扫描）时才会报警。一次扫描需要多少内存，见扫描速度与磁盘负载。

  • 关掉不需要的扫描和标签页。
  • 只开着很少的扫描、甚至没有扫描时警告仍然出现，请报告问题。这时日志文件里 memory above what the scans account for: 之后有一段明细，列出每个扫描的数据、视图和各个队列，请附上它。
  • 想再附上占用内存最多的代码行：设置环境变量 SPACEKNIFE_MEMTRACE=1 后启动 SpaceKnife，重现问题，附上新的明细。它会让 SpaceKnife 变慢，用完请去掉。

恢复设置

Section titled “恢复设置”

  • 一个设置页：页面底部的「恢复默认」。之后几秒内可以「撤销」。

  • 全部：「设置 › 高级 › 导入与导出 › 全部恢复默认…」确认后把所有设置和文件类别恢复为初始值。

  • 先留一份：同一页的「导出设置」把所有改过的设置和自定义的文件类别存成一个文件；「导入设置」会先列出会改变的项，确认后才生效。

  • 手动：退出 SpaceKnife，删除或重命名设置文件。文件里只记录你改过的设置。设置侧栏底部的「打开设置文件」可以打开它。

    系统 设置文件
    Windows %LOCALAPPDATA%\SpaceKnife\settings.json
    Linux ~/.config/SpaceKnife/settings.json
    macOS ~/Library/Application Support/SpaceKnife/settings.json

  • 设置文件损坏不会让 SpaceKnife 起不来：设置页顶部显示「设置文件不合法，继续使用上一次的有效设置：…」，你下一次修改设置时会写入一份完好的文件。

  • 「清除缓存…」（「设置 › 高级 › 扫描助手与缓存」）删除缓存的数据，正在使用的部分会保留。

  • 不动现有数据，干净地启动一次：把 SPACEKNIFE_HOME 设为一个空文件夹后启动 SpaceKnife，它就只用这个文件夹；去掉这个变量就回到原来的数据。

报告问题

Section titled “报告问题”

先搜索已有的 issue，再在 GitHub 上提交问题报告。用法上的疑问请到 Discussions › Q&A。

请附上：

  • 「复制诊断信息」的内容，至少要有版本、操作系统和安装方式。
  • 你做了什么、预期是什么、实际看到了什么；能重现的话写下步骤。
  • spaceknife.log 里相关的部分，最好是把日志级别设为「调试」后重现时的记录。
  • 扫描慢：scan done 和 scan profile 两行。内存警告：上文说的那段明细。

安全问题不要发公开 issue，请按 SECURITY.md 私下报告。