跳到主要内容

故障排查

Cleanr 已打开，但没有扫描​

这是正常行为。启动只会设置扫描根目录。按 s、运行 /scan，或按 u 执行用量扫描。

命令面板里没有 /review 或 /clean​

依赖扫描结果的命令会在扫描完成前隐藏。请先运行 /scan。如果扫描仍在进行， 等待完成，或按 Esc / x 取消。

扫描没有找到候选项​

请检查：

  • 对应规则包是否在 cleanup.enabled_rule_packs 中；
  • 目标是否被 ignore_dirs 或 ignore_patterns 排除；
  • 条目是否满足规则的大小、时间、名称或路径条件；
  • 条目是否达到本次生效的 [recommendations].preselect_after_days 修改时间年龄门槛。 cleanr analyze 会保留未达到门槛的证据；若其中已有规则命中，可修改设置，或有意地 使用 /scan --inactive-days <天数> 重新扫描；
  • 扫描的是包含候选项的目录，而不是把候选目录本身作为根目录。扫描根目录本身 永远不会成为清理候选项。

使用 /rules 查看已加载规则，使用 /plugins 确认自定义 bundle 是否被发现。

/scan --global 提示没有发现清理位置​

当前平台没有返回所选全局分类对应的已知用户级系统清理位置。仍然可以显式指定路径：

/scan /home/me/.cargo /home/me/.npm

请使用当前操作系统真实存在的绝对路径。TUI 中输入的路径不会展开 ~ 或 环境变量。

Agent 因扫描不完整而要求 macOS 完全磁盘访问权限​

使用 Cleanr Skill 不需要授予完全磁盘访问权限。Safari、CloudKit 或临时目录 无法读取时，可以保留为未检查范围。先查看 scan.issues：仅凭报告标为 partial，无法认定缺少隐私权限。

Skill 可以继续总结已有证据；需要准备清理计划时，在已授权范围内尝试一次缩小 范围的扫描。跳过的位置会明确列出，自动预选使用新一轮完整扫描的证据。为这个 较小范围生成计划时，应保持相同的根目录、配置和修改时间年龄策略。局部扫描 完整不代表原始范围已经全部检查。

plan 和 dry-run 都是只读操作；权限造成的部分证据并不直接禁止查看计划， 但默认选择可能为空。如果 scan.budget_exceeded 非空，该结果不能生成计划； 应缩小扫描范围，而不是修改权限。真正清理时仍需审阅并确认确切计划。

Cleanr 报告配置解析错误​

打印默认配置路径：

cleanr config path

如果使用自定义文件，排查时要带上相同的 --config。重点检查未知键、拼错的 枚举值、重复 ID 和无效 TOML。

在不覆盖原文件的情况下生成一份新默认配置用于对比：

cleanr --config /tmp/cleanr-default.toml config init

终端显示异常​

  • 确认终端支持 Unicode 和彩色显示。

  • Cleanr 默认使用便携的 ANSI 基础色。如果颜色仍变成整片红/绿块， 请重置终端配置，或换一个终端应用验证。

  • 如果只是背景明暗不对，再设置显式主题：

    cleanr config set ui.theme dark

  • 放大过小的终端窗口。

  • 如果程序被强制中断，在 Shell 中运行 reset 恢复终端状态。

已选条目在清理时被跳过​

Cleanr 会在执行前重新校验每个目标。如果条目在扫描后变化、变成符号链接、 移出扫描根目录或与受保护路径重叠，就会被跳过。请重新扫描并审阅新状态，不要 强制执行旧计划。

恢复失败​

常见原因包括：

  • 系统回收站已清空；
  • 条目被手动移出回收站；
  • 原路径已经存在；
  • 回收站元数据发生变化或不可用；
  • 当前平台不支持程序化恢复。

Cleanr 不会覆盖当前路径。排查期间请手动检查系统回收站，并保留 Cleanr 状态 目录和清单。

关闭更新检查​

Cleanr 最多每 24 小时检查一次新版本。可以关闭这个非阻塞启动检查：

Cleanr 0.16.0 及后续版本使用后台线程检查更新，HTTP 请求超时为 10 秒。首屏不等待网络； 发现新版本后在首页单独提示，不覆盖任务错误。

cleanr --no-update-check

或：

export CLEANR_NO_UPDATE_CHECK=true

全局扫描很慢或看似卡住​

可以选择启用配置中的扫描预算，限制保留条目、耗时、估算分配或保留 诊断。启用预算时使用单个遍历 worker；命中预算后返回只读部分证据。耗时上限采用协作 检查：它会在扫描阶段和文件系统操作之间检查，但无法中断已经阻塞在操作系统内核中的 元数据读取或目录读取。若内核调用最终返回，可以取消扫描；如果反复阻塞，应检查对应的 文件系统、挂载点或网络共享。

安装、升级或卸载问题​

快速开始提供系统/CPU 资产选择，以及升级、回退和卸载命令。版本没有 变化时，macOS/Linux 使用 command -v cleanr，PowerShell 使用 Get-Command cleanr 检查实际可执行文件。混用安装方式可能让 PATH 中存在多个版本。

清理总量没有变成可用空间​

移入系统回收站通常仍占用磁盘。候选大小或已移动字节数不是可用空间测量。回收站条目 与本地记录还在时，Cleanr 才可能恢复；清空回收站是另一个决定，也会移除恢复来源。

获取更多帮助​

如果问题可以稳定复现，请在 GitHub 提交 issue，并附上：

  • Cleanr 版本（cleanr --version）；
  • 操作系统和终端；
  • 安装方式；
  • 完整命令或按键步骤；
  • 去除密钥和个人路径后的完整错误信息。

安装、规则匹配或恢复问题请使用支持表单。 不要附上原始分析 JSON、计划或清单。疑似安全问题请使用 私密报告。