BleachBit 从源码运行与开发全指南:释放磁盘空间、维护隐私与自动化清理实战
BleachBit 从源码运行与开发全指南:释放磁盘空间、维护隐私与自动化清理实战
BleachBit 是一款面向 Windows 与 Linux 的系统清理工具,核心使命是清理文件以释放磁盘空间并维护隐私。本文以仓库根目录的 README.md 为主线,完整讲解如何在不安装的情况下从源码运行 BleachBit、如何通过 GUI 与 CLI 完成预览与删除,以及开发者如何安装依赖、运行测试、参与本地化并借助 Docker 为多个发行版构建安装包。读完本文,你将掌握 BleachBit 的完整启动链路、命令行参数体系、cleaner 定义机制与测试/打包工作流。
项目概览:BleachBit 能做什么
BleachBit 的核心目标只有两个:释放磁盘空间和维护隐私。它通过"清理器(cleaner)"机制工作——每个 cleaner 针对一个应用或系统区域(如 Firefox、Chrome、System),每个 cleaner 下又包含若干可勾选的 option(如 cache、cookies、tmp)。
在仓库中,cleaner 有两种来源:
- CleanerML 原生定义:位于 cleaners/ 目录下的 XML 文件,例如 cleaners/firefox.xml 用
<cleaner id="firefox">、<var>、<option>、<action>等标签描述清理项,其格式受 doc/cleaner_markup_language.xsd 约束; - 硬编码后端:例如
systemcleaner 直接在 bleachbit/Cleaner.py 中以System(Cleaner)类实现,注册了cache、tmp、trash、recent_documents、rotated_logs、empty_space、custom等跨平台选项,以及 Windows 专属的recycle_bin、prefetch、muicache、logs等。
register_cleaners()(见 bleachbit/Cleaner.py)负责把所有 cleaner 汇总到全局 backends 字典:先注册硬编码的 system,再加载 CleanerML 的 XML cleaner,在 Windows 上还会导入 Winapp2.ini 的 cleaner。
从源码运行:三步启动 BleachBit
README 给出了最核心的启动流程——无需安装,依次执行三个命令即可:
make install-deps # runtime deps (auto-detects Debian/Fedora/openSUSE/Arch)
make -C po local # build translations
python3 bleachbit.py
下面逐一拆解每一步的底层原理。
第一步:安装运行时依赖
make install-deps 实际调用 scripts/install-deps.sh(见 Makefile)。该脚本的核心能力是自动检测发行版族:通过 /etc/os-release 判断 Linux 发行版,通过 uname 判断 macOS 与 FreeBSD,支持六类系统(脚本头部注释明确列出):
| 发行版族 | 代表系统 | 包管理器 |
|---|---|---|
| debian | Debian、Ubuntu、Mint、Pop!_OS 等 | apt |
| fedora | Fedora、RHEL、Alma、CentOS 等 | dnf |
| opensuse | Tumbleweed、Leap | zypper |
| arch | Arch、Manjaro、EndeavourOS 等 | pacman |
| freebsd | FreeBSD | pkg |
| macos | macOS | pip(venv)+ Homebrew(开发工具) |
Linux 下运行时依赖以 GTK3 与 GObject 内省为主(如 Debian 的 gir1.2-gtk-3.0、libgtk-3-0、python3-gi),因为 BleachBit 的 GUI 基于 PyGObject/GTK3;同时会安装 xdg-utils、psutil、requests 等纯 Python 依赖(psutil 用于检测应用是否正在运行以避免误清,requests 用于检查在线更新和下载 winapp2.ini,见 requirements.txt)。
脚本还支持三个可追加参数:
./scripts/install-deps.sh # 仅运行时依赖
./scripts/install-deps.sh --dev # 运行时 + 构建/测试/打包依赖
./scripts/install-deps.sh --venv # 运行时依赖 + 创建 Python 虚拟环境
./scripts/install-deps.sh --dev --venv
其中 --venv 默认在仓库根目录创建 .venv(可用 VENV_DIR=/path 覆盖),并以 --system-site-packages 方式创建——这是因为 Linux 上 PyGObject 无法可靠地通过 pip 安装,必须复用系统包;--dev 则会额外安装 pytest、pylint、pyflakes、autopep8、shellcheck、gettext、xmllint 等开发/测试/打包工具。
README 同时提醒:许多 Linux 系统已自带这些基础依赖,可以跳过安装步骤;但若运行遇到问题,应优先排查缺失的依赖。
第二步:构建翻译文件
make -C po local
这条命令进入 po/ 目录执行 local 目标(见 po/Makefile):将每个 .po 翻译文件用 msgfmt 编译成 .mo,并软链接到仓库根目录 ../locale/<语言代码>/LC_MESSAGES/bleachbit.mo,使应用在未安装的情况下也能使用本地化界面。仓库 po/ 下收录了 af、ar、zh_CN、zh_TW 等数十种语言的翻译文件,并维护一个可再生的模板 po/bleachbit.pot。
第三步:启动应用
python3 bleachbit.py
bleachbit.py 是启动器脚本,其流程清晰地展示了 GUI 与 CLI 的分派逻辑:
- 调用
bleachbit.Bootstrap.bootstrap()(见 bleachbit/Bootstrap.py)完成环境准备:POSIX 系统下补全HOME、PATH、XDG_*等环境变量;Windows 下加固 DLL 搜索路径、设置 GTK 的GDK_PIXBUF_MODULE_FILE等; - 若没有命令行参数且当前有可用的显示环境(
is_gtk_available())且非 Wayland+root 冲突场景,则启动 GUI(bleachbit.GuiApplication.Bleachbit); - 否则进入 CLI 分支,调用
bleachbit.CLI.process_cmd_line()(见 bleachbit/CLI.py);若既无参数也无显示环境,则自动追加--help打印用法。
启动后,README 给出了 GUI 的标准使用流程:先检查偏好设置 → 勾选一些选项 → 点击 Preview 预览 → 审查文件列表、按需调整勾选 → 点击 Delete 真正删除。这个"先预览、后删除"的两阶段设计非常关键——预览阶段只扫描并列出将要删除的文件(Worker 以 really_delete=False 运行),删除阶段才执行实际写入操作,避免误删。
命令行接口:从 --help 到精细控制
README 建议通过以下命令查看命令行接口的完整用法:
python3 bleachbit.py --help
BleachBit 的命令行使用 optparse 实现(见 bleachbit/CLI.py),用法格式为:
usage: %prog [options] cleaner.option1 [cleaner.option2 ...]
即位置参数是 cleaner.option 形式的清理操作对,例如 system.tmp(清理系统临时文件)、firefox.cache(清理 Firefox 缓存)。核心选项如下:
| 选项 | 说明 |
|---|---|
-l, --list-cleaners |
列出所有可用 cleaner(输出如 system.tmp、firefox.cache) |
-p, --preview |
预览将要删除的文件及其他变更(不实际修改) |
-c, --clean |
执行清理,真正删除文件并做其他永久性更改 |
-s, --shred |
粉碎(shred)指定文件或文件夹,位置参数此时为路径 |
-w, --wipe-empty-space |
擦除给定路径中的剩余空间(注意:不能与 -p/-c/-s/-l 混用) |
-o, --overwrite |
用覆盖写入隐藏文件内容,仅建议与 --clean 配合(见 bleachbit/CLI.py) |
--gui |
强制启动图形界面 |
--preset |
使用之前在图形界面中保存的勾选方案 |
--all-but-warning |
启用所有不带警告的选项 |
--except |
排除某些 cleaner 选项(可重复传入,也支持逗号分隔) |
--debug |
将日志级别设为 verbose |
--debug-log |
将调试消息写入文件 |
--sysinfo |
输出系统信息 |
-v, --version |
输出版本信息并退出 |
--no-uac |
(仅 Windows)不提示管理员权限 |
--update-winapp2 |
(仅 Windows)若有新版则更新 winapp2.ini |
几个值得注意的行为细节(均有源码依据):
--except禁止通配符:args_to_operations()对--except中出现的*、?直接报错并以退出码 1 结束,避免过度清理(见 bleachbit/CLI.py);cleaner.*通配:位置参数中支持firefox.*形式,表示启用该 cleaner 的全部选项;- 互斥校验:
--list-cleaners、--wipe-empty-space、--preview、--clean、--shred一次只能指定其中一个,否则报错退出; - 已废弃选项自动迁移:
system.free_disk_space会自动转换为system.empty_space并给出日志提示(见 bleachbit/CLI.py)。
预览与删除的底层执行
无论 GUI 还是 CLI,实际执行都通过 bleachbit/Worker.py 中的 Worker 类完成。Worker.run() 明确分四个阶段(见 bleachbit/Worker.py):
- 常规清理:对每个选中的 option 执行其命令序列(
Command.Delete、Command.Shred、Command.Function等,见 bleachbit/Command.py); - 深度扫描(Deep scan):对声明了 deep scan 的路径做更大范围的搜索;
- 内存清理:Linux 下擦除 swap 与空闲内存;
- 擦除剩余空间:
empty_space操作被延迟到最后执行(优先级定义在 bleachbit/Worker.py),执行期间会实时显示进度百分比与预计剩余分钟数。
预览与删除由 Worker 的 really_delete 布尔值区分:CLI 的 --preview 传入 False,--clean 传入 True。删除时还会先调用 backends[operation].is_process_running() 检查目标应用是否正在运行(例如清理 Firefox 前若发现 Firefox 进程存在,会拒绝清理并提示关闭应用)。
开发与测试:安装、测试、lint 与格式化
安装开发依赖
make install-deps-dev
等价于 ./scripts/install-deps.sh --dev,在运行时依赖之外额外安装构建、测试、lint 与打包工具,包括 pytest/pytest-xdist、pylint、pyflakes、autopep8、shellcheck、gettext、desktop-file-utils、debhelper(Debian)/rpm-build(RedHat 系)等。
常用开发命令
README 汇总了三个高频命令:
make tests # run tests
make lint # check .py and .sh files for issues
make pretty # format .py and .xml files
make tests(见 Makefile):依次执行——po目录的翻译文件检查(msgfmt --check)、cleaners目录的 XML 校验(用xmllint --schema doc/cleaner_markup_language.xsd逐一验证,见 cleaners/Makefile)、以及PYTHONWARNINGS=error条件下的 Python 单元测试(unittest discover -p Test*.py,覆盖 tests/ 下如 tests/TestCLI.py、tests/TestCleaner.py 等模块);make lint(见 Makefile):并行运行 shellcheck、pyflakes、pylint、autopep8 与 appstreamcli 校验,日志分别写入all.shellcheck.log、all.pyflakes.log、all.pylint.log、all.autopep8.log;make pretty(见 Makefile):用 autopep8 格式化.py、用 xmllint 格式化.xsd,并调用cleaners/Makefile的pretty目标统一 XML 缩进。
另有 make tests-pytest(pytest + xdist 并行)、make tests-with-sudo(运行需要 sudo 的测试,见 tests/test_with_sudo.py)等进阶入口。
本地化:翻译贡献工作流
README 指向了 翻译文档 与 Weblate 平台。仓库侧的实际支撑如下:
- 全部翻译源文件位于 po/ 目录,以 ISO 语言代码命名(如
zh_CN.po、zh_TW.po); - 模板 po/bleachbit.pot 由 po/Makefile 的
$(POTFILE)目标生成,聚合了 Python 源码字符串、CleanerML 清理器文案、桌面文件(.desktop)与 AppStream 元数据(.metainfo.xml)中的可翻译内容; - 常用命令:
make -C po refresh-po(用新模板合并刷新所有.po)、make -C po local(本地编译并部署.mo)、make -C po tests(校验.po格式)、make -C po spelling(用 aspell 检查拼写)。
许可证
README 明确:BleachBit 本身(包括源码与 cleaner 定义)采用 GNU GPL 第 3 版或(由你选择)任何更高版本,完整许可证文本见 COPYING;仓库中随附的 markovify(位于 bleachbit/markovify/,用于 GUI 中生成随机示例文本等)采用 MIT 许可证。相关版权声明(2008–2026 Andrew Ziem)同时出现在 Makefile、bleachbit.py 等文件的文件头。
基于 Docker 的 Linux 多发行版构建
README 提供了一种可复现的打包方案:
./docker/build.sh <distro> # distro is one of {debian, fedora, opensuse}
构建产物会被复制到宿主机 ./docker-artifacts/<distro> 目录。在本仓库快照中,docker/ 目录实际包含的是配套的构建基础设施(docker/build.sh 之外):
- docker/Dockerfile.debian:基于
debian:trixie,预装python3-gi、gir1.2-gtk-3.0、debhelper、devscripts、lintian等,供 Debian 系打包; - docker/Dockerfile.fedora 与 docker/Dockerfile.opensuse:对应 RedHat 系与 openSUSE 的 RPM 打包环境;
- docker/Dockerfile.appimage:用于
make appimage产出 AppImage 单文件分发; - docker/Dockerfile.py314-pytest:在 Python 3.14 上运行完整 pytest 测试矩阵;
- docker/inside_container.sh:容器内执行的核心脚本——根据
DISTRO_NAME环境变量分流:debian 走dpkg-buildpackage -us -uc -b,fedora/opensuse 走rpmbuild -ba bleachbit.spec(借助 bleachbit.spec 与 debian/ 目录下的 control/rules 文件),appimage 走make appimage;可用SKIP_TESTS环境变量跳过make tests以加速打包。
进一步深入的方向
- CleanerML 标记语言:想为某个应用编写清理器,可参照 cleaners/firefox.xml 的完整示例,并通过 doc/cleaner_markup_language.xsd 校验格式;
- CleanerML 解析实现:bleachbit/CleanerML.py 负责把 XML 编译成可执行的
Command; - GUI 行为细节:bleachbit/GuiWindow.py、bleachbit/GuiTreeModels.py 实现了 cleaner 树形勾选与预览/删除的交互;
- 偏好存储:用户选择以 INI 形式持久化,读取与写入逻辑见 bleachbit/Options.py(默认值表在 bleachbit/Options.py),
--preset正是从其中的tree小节恢复 GUI 勾选(见 bleachbit/CLI.py)。
综上,从"三行命令跑起来"到"自定义 cleaner、跑测试、打安装包",BleachBit 的整个生命周期都有清晰的代码与构建链路支撑:以 README.md 为入口、以 Makefile 为枢纽、以 scripts/install-deps.sh 和 po/Makefile 为依赖与本地化基础,最终统一收敛到 bleachbit.py 这个启动入口上。