🔖 Bookmark Cleaner

浏览器收藏夹失效链接批量清理工具

一键检测并清理浏览器收藏夹中的死链、404页面、重复书签和空文件夹

📑 目录

项目简介
核心功能
快速开始
命令参数
使用示例
输出文件说明
常见问题
安全声明
更新日志
开发规划
贡献指南
开源协议

📖 项目简介

日常使用浏览器会积累大量收藏链接，长期使用后会产生失效链接、404 页面、过期域名、重复书签、空文件夹等问题，手动清理耗时费力。

Bookmark Cleaner 是一款基于 Python 开发的书签整理工具，专门针对浏览器导出的 HTML 书签文件进行批量检测与清理。

🎯 设计理念：简单、高效、安全 —— 让书签清理变得轻松愉快

工具采用多线程并发检测，内置完善的异常处理与日志系统，全平台兼容，安全稳定。

✅ 支持浏览器

✨ 核心功能

🔍 智能链接检测

自动识别 400~599 各类失效状态码，精准标记死链
区分可疑链接（401/403/429/503/504），支持自定义保留/删除
自动跳过短链接域名、本地文件、磁力链等非 HTTP/HTTPS 链接
细化错误类型：连接超时、SSL 证书错误、DNS 解析失败、连接重置、重定向异常等
优先使用 HEAD 请求，请求失败自动降级为 GET 请求重试

🧹 一键自动清理

批量删除所有失效链接
递归清理空书签文件夹，兼容多浏览器书签格式
一键去重，自动移除重复书签（仅保留唯一链接）
运行前自动备份原始书签，彻底避免数据丢失

📊 多格式报告输出

文本报告 report.txt：分类展示死链、可疑链接、重复链接
CSV 表格报告：支持 Excel / WPS 直接打开查看与统计
独立错误日志 error.log：单独汇总检测异常、请求失败链接

⚙️ 增强特性

自适应多线程并发，合理利用系统硬件资源
全局请求连接池 + 随机延迟重试，有效规避网站封禁
完整代理支持，适配特殊网络环境
支持文件夹黑白名单、指定域名筛选检测
全平台终端适配：Windows / Linux / macOS 颜色、进度条正常显示
提供静默模式、详细日志、免交互执行，可用于自动化脚本/服务器定时任务

🚀 快速开始

1. 环境要求

Python 3.8 及以上版本

2. 安装依赖

💡 提示：建议使用虚拟环境安装

pip install requests beautifulsoup4

3. 导出浏览器书签

使用工具前，先将浏览器收藏夹导出为标准 HTML 文件：

🔹 Chrome / Edge 导出步骤

打开书签管理器（快捷键：Ctrl+Shift+O）
点击右上角菜单 → 导出书签
保存为 bookmarks.html

🔹 Firefox 导出步骤

书签 → 管理书签（快捷键：Ctrl+Shift+B）
导入和备份 → 导出书签到 HTML

🔹 Safari 导出步骤

文件 → 导出 → 书签
选择保存位置，保存为 HTML 文件

4. 基础运行

将导出的 bookmarks.html 与脚本 check_bookmarks.py 放在同一目录，执行基础命令：

# 常规检测 + 清理失效链接 + 自动备份原文件
python check_bookmarks.py bookmarks.html

📝 完整命令参数

usage: check_bookmarks.py [-h] [-o OUTPUT] [-w WORKERS] [-t TIMEOUT] [-p PROXY]
                          [--csv CSV] [--keep-suspicious] [--dry-run]
                          [--no-confirm] [--only-folder ONLY_FOLDER]
                          [--exclude-folder EXCLUDE_FOLDER] [--domain DOMAIN]
                          [--quiet] [--verbose] [--deduplicate] [-v]
                          input

Bookmark Cleaner v1.1.0 - 浏览器收藏夹失效链接清理工具

positional arguments:
  input                 输入的收藏夹 HTML 文件路径

options:
  -h, --help            显示帮助信息并退出
  -o, --output OUTPUT   输出文件名 (默认: bookmarks_cleaned.html)
  -w, --workers WORKERS 并发线程数 (默认: 自动适配CPU，上限50，建议 30-100)
  -t, --timeout TIMEOUT 请求超时秒数 (默认: 8，建议 5-8)
  --fast                极速模式：timeout=5, workers=80, retries=0（大幅提速，适合千链接级任务）
  -p, --proxy PROXY     设置HTTP代理，格式: http://127.0.0.1:7890
  --csv CSV             导出CSV格式报告，指定文件路径
  --keep-suspicious     保留可疑链接(403/429/503等)，不自动删除
  --dry-run             仅检测链接，不生成清理后的文件（试运行）
  --no-confirm          跳过交互确认，直接执行清理（适合脚本运行）
  --only-folder ONLY_FOLDER
                        仅检测指定文件夹（部分匹配）
  --exclude-folder EXCLUDE_FOLDER
                        排除指定文件夹（部分匹配）
  --domain DOMAIN       仅检测指定域名（例：github.com）
  --quiet               静默模式，仅输出最终结果
  --verbose             详细模式，打印每一条链接的检测结果
  --deduplicate         移除重复书签，仅保留唯一链接
  -v, --version         查看程序版本

🧪 常用使用示例

场景	命令
试运行（推荐）	`python check_bookmarks.py bookmarks.html --dry-run`
极速扫描（新增）	`python check_bookmarks.py bookmarks.html --fast`
极速 + 代理	`python check_bookmarks.py bookmarks.html --fast --proxy http://127.0.0.1:7890`
清理 + 去重	`python check_bookmarks.py bookmarks.html --deduplicate`
搭配代理	`python check_bookmarks.py bookmarks.html --proxy http://127.0.0.1:7890`
保留可疑链接	`python check_bookmarks.py bookmarks.html --keep-suspicious`
导出CSV报告	`python check_bookmarks.py bookmarks.html --csv report.csv`
仅检测指定文件夹	`python check_bookmarks.py bookmarks.html --only-folder "工作"`
静默执行（脚本用）	`python check_bookmarks.py bookmarks.html --no-confirm --quiet`

📂 输出文件说明

工具运行后，会在原文件同目录自动生成以下文件：

文件名称	用途说明
📦 `xxx_backup.html`	原始书签自动备份文件，防止误操作丢失数据
✨ `bookmarks_cleaned.html`	清理完成后的书签文件，直接导入浏览器即可使用
📄 `report.txt`	综合文本报告，包含统计数据、死链、可疑链接、重复链接
❌ `error.log`	独立错误日志，记录检测异常、请求失败的链接
📊 自定义 `.csv`	结构化表格报告，包含 URL、状态、原因、文件夹、重复次数

Tip

首次使用强烈建议先加上 --dry-run 试运行，核对检测结果无误后再执行清理！

❓ 常见问题

Note

点击问题展开查看详细解答

Q: 为什么有些网站明明能打开却被标记为失效？

主要原因：

Cloudflare 反爬：返回 403，已被标记为 "可疑链接"，加 --keep-suspicious 可保留
地区限制：服务器在国外，国内检测超时，使用 --proxy 即可
User-Agent 拦截：已使用最新 Chrome UA，大部分网站可通过

Q: 几千条链接会不会很慢？

性能参考（20线程）：

1000 条链接：约 1-2 分钟
5000 条链接：约 5-10 分钟
10000 条链接：约 10-20 分钟

可通过 --workers 参数调整并发数提升速度。

Q: 会泄露我的收藏夹数据吗？

绝对不会！

所有检测都在本地完成
代码完全开源可审计
没有任何数据上传行为
仅发起 HTTP HEAD/GET 请求检测链接可用性

Q: 清理后文件夹结构会乱吗？

不会！ 完美保留：

原有的文件夹层级结构
嵌套关系和顺序
书签名称和添加时间
只会删除失效链接条目

🛡️ 安全声明

Important

你的数据安全是我们的首要考虑

✅ 本工具纯本地运行，不会上传任何书签、链接、隐私数据至外网
✅ 每次运行自动备份原始书签文件，多重保障数据安全
✅ 网络请求仅用于检测链接可用性，无数据采集、窃取行为
✅ 代码完全开源，可自由查阅、审计与二次开发

📋 更新日志

v1.1.0 (2026-07-12) — 当前稳定版

🛠️ 核心修复

修复导入缺失导致的启动崩溃：补全 argparse 模块导入，解决 NameError: name 'argparse' is not defined 问题
修复文件编码读取失败：新增多编码尝试机制（UTF-8、GBK、GB2312、UTF-16），自动回退到 errors='replace'，彻底解决中文路径、BOM 头、编码混杂导致的读取报错
修复短链接域名匹配不精准：优化域名提取逻辑，严格匹配二级域名，避免误判 sub.t.co.example.com 等非短链接域名
修复重复计数统计错误：使用 Counter 统计所有书签 URL，而非仅统计独立 URL，报告中重复次数显示正确
修复可疑/失效链接分类边界：明确区分“死链（400-599）”、“可疑链接（401/403/429/503/504）”、“跳过检测（短链接/非HTTP）”，报告统计数值一致

⚡ 性能优化

全局请求会话复用：引入 requests.Session + HTTPAdapter 连接池，配合 Retry 策略，显著降低 TCP 握手与 TLS 握手开销
自适应并发线程数：基于 multiprocessing.cpu_count() 动态计算 MAX_WORKERS = min(50, cpu_count * 4 + 2)，网络 IO 密集型场景充分利用带宽
默认参数收敛：超时 10s→8s，重试 2→1，并发上限 20→50，综合提升 ~40% 吞吐
随机退避重试：失败重试间加入 0.2 + random.uniform(0.1, 0.5) 秒抖动，有效规避目标站点限流/封禁
HEAD 优先 + GET 降级：默认使用轻量 HEAD 请求，遇到 405/501 自动降级为流式 GET，兼容不支持 HEAD 的站点
新增极速模式 --fast：一键开启 timeout=5, workers=80, retries=0，千链接级任务可从 20 分钟压缩至 2-3 分钟

🔒 安全与隐私增强

URL 敏感参数自动脱敏：报告与日志中自动将 token、access_token、api_key、secret、password、session、jwt、oauth_token 等 30+ 类敏感 Query 参数值替换为 ***，防止隐私泄露
运行前自动备份：每次执行均自动生成 xxx_backup.html，原子化写入清理后文件，断电/崩溃也不丢数据
纯本地运行零上传：代码完全开源，无任何遥测、上报、云端同步行为

📊 报告与输出增强

多格式报告：新增 CSV 导出（utf-8-sig 兼容 Excel 中文）、独立错误日志 error.log
结构化统计：文本报告新增“检测条件筛选记录”“重复书签统计（按次数降序）”“详细耗时统计”
进度条实时统计：显示 ✅有效 / ❌失效 / ⚠️可疑 / ⏭️跳过四类计数，含 ETA 预估

🧱 代码质量重构

模块化拆分：核心逻辑拆分为 check_url / sanitize_url / extract_bookmarks / remove_dead_bookmarks / clean_empty_folders / deduplicate 等独立函数，单一职责、易测试
类型注解完善：全面使用 Python 3.10+ | 语法与 tuple[str, bool | None, str, bool] 等精确类型提示
异常处理细化：区分 Timeout、SSLError、ConnectionError(含 DNS/拒绝/重置)、TooManyRedirects 等 6 类异常，错误信息更具可读性
终端兼容增强：Windows 下自动开启 ENABLE_VIRTUAL_TERMINAL_PROCESSING 与 UTF-8 代码页，颜色/进度条/中文正常显示；非 TTY 环境自动降级纯文本

🐛 问题反馈 & 开发规划

兼容性说明

完全兼容主流浏览器导出的标准 HTML 书签文件
Windows CMD / PowerShell、Linux、macOS 终端均正常适配颜色与进度条

问题反馈

如果遇到 Bug、兼容性问题、功能建议，欢迎提交 Issues

后续开发计划

v1.2 (近期规划)

JSON 格式书签支持：原生支持 Chrome/Edge/Brave 导出的 Bookmarks JSON 格式（无需先转 HTML）
重定向链自动解析与更新：检测 301/302/307/308 重定向，自动将旧 URL 更新为最终落地 URL，可选 --update-redirects
链接去重高级策略：支持按“标题+URL”双重去重、保留最新/最旧、按文件夹优先级保留
增量扫描模式：基于文件修改时间或书签添加时间，仅检测新增/变更链接，大幅提升二次扫描速度

v1.3 (中短期规划)

书签分类与标签系统：基于域名、关键词、页面内容自动打标签，支持自定义规则文件
文件夹批量重命名/合并/拆分：支持正则替换、前缀/后缀添加、同名文件夹智能合并
死链归档而非删除：新增 --archive-dead 参数，将失效链接移动到“🗂️ 已归档”文件夹而非直接删除
配置文件支持：~/.bookmark-cleaner.yaml 存储默认代理、超时、并发数、输出目录等，避免每次输入参数

v2.0 (长期规划)

跨平台图形化界面 (GUI)：基于 PySide6/Tauri 开发原生桌面端，支持拖拽导入、可视化进度、结果交互式筛选
浏览器扩展同步：开发 Chrome/Edge/Firefox 扩展，实现“一键扫描当前书签栏”“自动同步清理结果回浏览器”
分布式/远程扫描：支持通过 SSH/代理在远程服务器/NAS 上运行扫描，本地仅做调度与结果聚合
AI 辅助内容分析：可选集成本地 LLM（如 Ollama），对疑似死链的页面标题/摘要进行语义判断，减少误判

v2.1+ (探索性功能)

书签健康度评分仪表盘：Web 版 Dashboard，展示域名存活率、重复率、空文件夹率、重定向链深度等多维指标
团队/企业版功能：多用户配置隔离、审计日志、RBAC 权限、定时任务调度、钉钉/飞书/Slack 通知

🤝 贡献指南

欢迎提交 Pull Request 参与项目开发！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 开源协议

本项目基于 MIT License 开源。

你可以自由使用、修改、分发本项目代码，使用时请保留原始开源协议声明。

🙏 致谢

感谢以下优秀开源库提供技术支持：

requests — 简洁强大的 HTTP 请求库
BeautifulSoup4 — HTML/XML 解析工具

⭐ 支持项目

如果这个工具帮到了你，请给个 Star ⭐ 支持一下！

Made with ❤️ for a cleaner bookmark experience

⬆ 回到顶部

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
assets		assets
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
check_bookmarks.py		check_bookmarks.py

Folders and files

Latest commit

History

Repository files navigation