说实话我一开始真没把磁盘空间当回事直到连续两次在本地构建大型前端项目时IDE 直接卡死系统弹窗明晃晃地告诉我“启动磁盘已满”。打开磁盘分析工具一看好家伙~/.npm、~/.cache/pip、~/Library/Caches这些目录加一起快 60GB堆的全是各种仓库包缓存。手动删了几次过两周又满而且每次删都提心吊胆生怕把正在用的依赖版本给清了。后来我们团队干脆自己写了一个开源的仓库包缓存清理工具按包管理器逐个扫描、智能判定可清理项、支持配置白名单和自动化调度。这篇博文就把这个项目的设计思路、核心机制、完整实操流程以及我们踩过的坑全部整理出来给同样被磁盘告急困扰的开发者一个可以直接抄作业的解决方案。1. 磁盘告急不是错觉开发者的缓存到底有多能吃1.1 拆开各家包管理器的缓存目录我吓一跳我见过太多同事遇到磁盘满的第一个反应是“删电影”、“删照片”结果清理完系统缓存一看真正的大头全在开发工具链里。不同语言、不同包管理器都有自己的缓存机制它们之间相互独立但有一个共同点默认不设上限只增不减。以我手头一台开发机为例逐一拆解各缓存目录的真实占用包管理器默认缓存路径实测占用为什么会这么大npm~/.npm/_cacache约 8.6GB每执行一次npm install依赖包的 tarball 和 metadata 都会缓存版本分支多时特别膨胀pip~/.cache/pip约 12.2GBpip 下载的 wheel 包全部缓存在这里多个 Python 虚拟环境共享同一份缓存pnpm~/.local/share/pnpm/store约 6.4GBpnpm 采用全局内容寻址存储虽节省了重复下载但老版本包不会被自动清理yarn~/.cache/yarn约 3.1GB原理与 npm 类似yarn v1 的缓存结构更松散Maven~/.m2/repository约 15.8GB所有历史依赖的 pom 和 jar 完整保留且不区分版本是否仍被引用Gradle~/.gradle/caches约 7.5GB包含已解析的依赖、构建缓存、转换缓存量级随项目数量线性增长Go Module$GOPATH/pkg/mod/cache约 2.3GB模块缓存与模块源码都存储在本机清理需要额外注意版本锁定的问题Rust/Cargo~/.cargo/registry约 1.8GBcrate 源码和压缩包缓存在 registry 下解压后的 src 占用更大这不是个例。如果你同时做前端、后端偶尔玩一点 Python 脚本和 Android 构建那机器上随便就能堆出 40GB 以上的缓存目录。关键问题是这些缓存目录本身设计为“安全可删”但大多数开发者并不清楚哪些是依赖缓存、哪些是项目代码、哪些是构建产物自然不敢乱动。1.2 手动清理为什么总清不干净我也尝试过手动清理路径倒是都知道但有几个痛点始终没解决。不同包管理器的清理命令不统一。npm 有npm cache clean --forcepip 是pip cache purgeyarn 是yarn cache cleanGradle 需要手动删除整个caches目录Go 的要靠go clean -modcache。每个命令的清理力度、安全边界都不一样记错就得翻文档。更麻烦的是“清理时机”问题。很多缓存清理命令是整体清除比如npm cache clean --force会把整个_cacache全删掉不留任何余地。而你本地的某个依赖版本可能只在旧项目里用到一旦被清掉下次运行旧项目就得重新下载等于把耗时换成了空间不划算。还有一类缓存非常隐蔽比如 Gradle 的构建缓存、Docker 的 overlay2 镜像层缓存、Homebrew 的下载缓存。它们分布在系统各处单靠“清理软件”或“存储分析工具”并不一定能准确识别哪些能被安全删除。这就引出了我们做这款工具的动机与其记一堆命令、人工判断不如把规则集中起来做成一个可扫描、可预览、可配置的清理工具。2. 清理工具的核心运行逻辑先扫描、再判断、后清理2.1 扫描层它到底是怎么找到缓存的别以为只是简单地遍历目录真正要安全清理必须先搞明白每个文件夹里装的是什么。我们的工具把扫描分为三个层级。第一层是静态识别。直接检查各包管理器约定的缓存路径是否存在比如~/.npm、~/.cache/pip、~/.m2/repository这一层用于快速定位和大致估算体积。第二层是元数据解析。以 npm 的_cacache为例目录里有content-v2和index-v5两个子目录里面是经过 hash 处理的二进制文件直接删文件是粗暴的做法应该借助cacache库来读取索引获取每个缓存条目对应的包名和版本号。第三层是版本关联分析。我们会扫描当前机器上所有项目的package-lock.json、pnpm-lock.yaml、pipfile.lock等锁文件构建出“当前仍在使用的版本集合”只有不在此集合中的缓存条目才被判定为可清理。这套机制的最大价值是“我删掉的确定都是没用的”。而不是简单粗暴地把缓存目录清空。以下是伪代码级别的扫描流程示例以 npm 缓存为例func scanNpmCache(cacheDir string, activeVersions map[string][]string) ([]CacheEntry, error) { entries : []CacheEntry{} // 使用 cacache 索引读取缓存条目 index, err : cacache.List(cacheDir) for entry : range index { pkgName, pkgVersion : parseCacheKey(entry.Key) if !isVersionActive(activeVersions, pkgName, pkgVersion) { entries append(entries, CacheEntry{ Path: entry.Path, Size: entry.Size, PkgName: pkgName, Version: pkgVersion, }) } } return entries, nil }扫描完后工具会生成一份详细的清理报告包含每条可清理项的名称、版本、占用体积、最后被访问时间。开发者可以先看报告确认无误后再执行清理。2.2 判定策略哪些缓存能删哪些不能动这是整个工具的灵魂。我见过很多“存储清理工具”把缓存目录整个标记为“可删除”使用体验确实粗暴误删风险也极高。我们的工具把这些缓存分成四类每一类采用不同的判定策略。第一类是无条件可清理缓存。典型的是构建过程产生的临时文件比如 Gradle 的transforms-*目录、pip 解压后的临时目录这类缓存即使删掉也不会影响任何已安装的依赖只是下次构建时会重新生成。这类条目会直接进入可清理列表。第二类是按版本保留缓存。以 Maven 的~/.m2/repository为例工具会解析当前机器所有 Maven 项目pom.xml以及gradle.lockfile实际引用的版本把未被引用的旧版本加入清理列表。同时提供一个“保留最近 N 个版本”的选项防止切分支时频繁重新下载。第三类是时间阈值缓存。npm 和 pip 这类缓存支持记录最后访问时间我们可以设置一个阈值比如“30 天内没有访问过的缓存才清理”。默认清理时不会动最近使用过的包保证开发体验。第四类是需要人工确认的重点关注缓存。比如 Go module 缓存如果你同时维护多个 Go 项目且使用了本地replace指令模块缓存里的源码可能被项目直接引用这时候自动删除是有风险的。工具会把这一类单独在报告中标注“建议手动确认”默认不勾选。2.3 安全保护删错了也能救回来即便是设计了这么细的判定策略依然会遇到边界情况。我们干脆给工具加了回收站机制。清理动作不是直接rm -rf而是先把待删除文件移动到一个隐藏的回收目录比如~/.pkgcache-cleaner/trash/并记录一份 JSON 格式的元数据原始路径、删除时间、所属包管理器。如果开发者在清理后发现自己本地某个项目依赖缺失可以用pkgcache-cleaner restore entry-id一键恢复。同时工具的默认配置遵循“先预览后执行”的安全模式。执行清理命令时如果没有显式添加--yes参数工具只会输出清理计划和预计释放空间不会做任何破坏性操作。这个设计在我后续接 CI/CD 定时任务时帮了大忙后面细说。3. 从零上手安装、首次扫描与一次安全清理3.1 安装方式与运行环境工具目前支持三大主流平台Linuxx86_64/arm64、macOSApple Silicon 与 Intel、Windows通过 WSL 或者原生二进制。安装方式我推荐直接使用预编译二进制不依赖额外的运行时也不污染全局环境。# Linux / macOS curl -fsSL https://pkgcache-cleaner.example.com/install.sh | sh # macOS 也可以通过 Homebrew brew tap pkgcache-cleaner/tap brew install pkgcache-cleaner # Windows使用 scoop scoop bucket add pkgcache https://pkgcache-cleaner.example.com/scoop-bucket scoop install pkgcache-cleaner代码仓库里的源码编译也很简单核心逻辑用 Go 编写一个二进制文件搞定。为什么要用 Go一个重要原因是它编译出的静态二进制不依赖 glibc 版本放哪都能跑另一个原因是 Go 标准库的filepath.Walk和并发控制写起来顺手扫描几十 GB 目录时能达到不错的吞吐。3.2 第一次扫描不要急着删先看报告装好之后直接执行pkgcache-cleaner scan这条命令会扫描所有已识别的包管理器缓存并在终端输出类似这样的汇总表格Scanning... 共发现 6 个可扫描的缓存目录 --------------------------------------------------------------------------------------------- | 包管理器 | 缓存路径 | 扫描结果 | --------------------------------------------------------------------------------------------- | npm | /home/user/.npm/_cacache | 8.6 GB | | pip | /home/user/.cache/pip | 12.2 GB | | pnpm | /home/user/.local/share/pnpm/store | 6.4 GB | | maven | /home/user/.m2/repository | 15.8 GB | | gradle | /home/user/.gradle/caches | 7.5 GB | | cargo | /home/user/.cargo/registry | 1.2 GB | ---------------------------------------------------------------------------------------------扫描之后生成完整的可清理候选列表并按“预计释放空间”排序的前 20 条会展示出来。每条数据都标注了包名、版本、缓存路径和体积让你清楚自己即将删掉的是什么。这里必须强调第一次使用请务必执行pkgcache-cleaner scan --report/tmp/clean-report.json把完整报告导出来打开看一眼。尤其是 Maven 和 Gradle 的部分确认里面列出的“可清理版本”确实没有你正在维护的项目的依赖然后再进入下一步。3.3 执行清理并设定保留策略预览确认没问题后我一般会加上一个保留策略参数再执行pkgcache-cleaner clean --keep-last 3 --min-age 30d --yes参数含义很简单--keep-last 3对于同一包名的多个历史版本只保留最近 3 个版本其余清理--min-age 30d只清理最后访问时间超过 30 天的缓存项--yes跳过交互确认直接执行这条命令跑完后工具会打印释放空间统计并列出所有被移动进回收站的条目数量和总大小。如果需要从回收站恢复pkgcache-cleaner list-trash pkgcache-cleaner restore entry-id最让我放心的是restore会依据元数据把文件原样放回原路径即使是符号链接或较长的嵌套目录也能还原。当然回收站里的文件也会占用磁盘空间所以工具提供了trash purge命令确认一段时间内没有异常后手动清除。4. 自动化实践定时清理与 CI 场景下的磁盘瘦身4.1 配置定时任务给开发机设置清理周期开发机上缓存增长的速度远比想象中快。尤其是每天要拉多个分支、频繁切换版本的同学缓存会呈现指数级累积趋势。手动想起才清理一次完全跟不上节奏。我现在的习惯是在每台开发机上配置两个定时任务一个“温和清理”每周执行一次一个“深度清理”每月执行一次。linux 上用 cronmacOS 上我用 launchd配置方式如下# 每周末凌晨 3 点执行温和清理 0 3 * * 0 /usr/local/bin/pkgcache-cleaner clean --keep-last 2 --min-age 7d --yes /var/log/pkgcache-cleaner.log 21如果你用的是 macOS 的 launchd可以写一个简单的 plist 文件放到~/Library/LaunchAgents/下再用launchctl load加载。这里有一个小细节定时任务里必须使用绝对路径因为 launchd 和 cron 的环境 PATH 通常不包含pkgcache-cleaner所在的目录我最初就吃过这个亏任务静默失败了两周。4.2 在 CI Runner 上给构建缓存做“瘦身”CI 流水线里仓库包缓存工具的用武之地比本地还大。GitHub Actions 的缓存actions/cache、自建 GitLab Runner 的 Maven/Gradle 缓存一旦不清理几十 GB 的磁盘很容易在几周内被耗光。我使用的方式是在 CI 流程末尾加一步“回收磁盘空间”- name: Clean caches run: | pkgcache-cleaner clean \ --keep-last 2 \ --min-age 3d \ --allowed-managers npm,pip,maven,gradle \ --yes--allowed-managers参数很关键它限制只处理指定的包管理器缓存避免误伤容器镜像或系统包缓存。如果 Runner 是用 Docker 容器跑的那还需要留意挂载目录的权限一般建议将pkgcache-cleaner安装在 Runner 宿主机的/usr/local/bin下通过宿主机 cron 定时清理而不是在流水线里直接删挂在容器里的目录原因在于容器内的删除操作对 overlay 文件系统上的文件并不会真正释放宿主机块。4.3 多机器批量管理的配置同步方案当团队里有 5 台以上开发机或几十台 CI Runner 时逐台机器手敲命令就不现实了。我们的解法是把工具默认配置抽离成一个 YAML 文件集中管理通过 Ansible 或自定义脚本下发给各台机器。配置文件大致长这样strategy: keep_last: 3 min_age_days: 30 scan_depth: full managers: npm: enabled: true extra_paths: [] pip: enabled: true maven: enabled: true keep_versions_by_package: 3 gradle: enabled: true go: enabled: false # Go 模块缓存默认不自动清 protect: paths: - /data/ci-cache/maven-repo # 这里指定永远不清的目录 log_level: info配置文件通过/etc/pkgcache-cleaner/config.ymlLinux或~/Library/Application Support/pkgcache-cleaner/config.ymlmacOS读取。这样即使每个人手动调用工具也用同一套策略。5. 实战中踩过的坑及对应的修复方案5.1 把 pip 缓存当垃圾清掉后离线安装失败了这是我自己踩得最惨的一次。团队某台 CI Runner 出于安全要求不能连外网所有 Python 依赖只能通过内网 PyPI 镜像下载同时本地保留一份“离线缓存包”。原本工具的策略是保留所有 pip 缓存但有一次我为了给Runner 腾空间临时手动改了配置把--min-age设成了0d结果把离线依赖缓存全打进了回收站。等流水线跑起来才发现需要离线安装的包一个都没有流水线全部失败。后来我在配置里加了两个保护机制一是在protect.paths中明确列出离线缓存目录二是为关键包管理器单独设一个allow_clean: false开关。对大多数开发者来说把“公司内部专用的离线 wheel 目录”或“特定项目的 vendor 目录”列为受保护路径是很有必要的。5.2 权限不够导致 Gradle 缓存清理失败还差点报警Gradle 缓存目录的文件属主不一定是当前用户尤其是当多个开发账号共用同一台机器或用sudo跑过 Gradle 构建时。用普通用户执行清理部分文件会因permission denied失败但直接sudo pkgcache-cleaner又可能把回收站的元数据写到 root 目录下导致普通用户后续无法执行restore。建议的解决方式是先用普通用户身份跑scan识别出需要清理但无权限的目录再单独用sudo pkgcache-cleaner clean --targets /home/user/.gradle/caches --yes处理。工具在无权限清理时的处理策略是跳过并继续而不是中断整个任务这样至少能先释放大部分空间。不过要注意涉及用户级缓存的清理最好还是在目标用户自己的会话下执行避免权限混乱。5.3 清理 Docker 缓存时不能只盯着/var/lib/dockerDocker 的镜像层、构建缓存和 overlay2 目录往往比包管理器缓存更占空间。标题虽然说的是“仓库包缓存”但实际开发者的磁盘告急通常是多个源头叠加的结果。我们把 Docker 的缓存识别做了扩展/var/lib/docker下的buildkit构建缓存、容器运行后残留的 overlay2 目录以及docker system prune命令能释放的那部分空间都会单独列出。实际处理有一个主次关系先用包管理器清理工具释放本机包缓存再执行docker system prune -f清理悬空镜像和构建缓存。后者对运行中的容器是安全的不会伤到正在使用的镜像层。5.4 误删后的恢复回收站不是保险箱有容量上限回收站机制虽好但内部有一个容量上限。默认配置是“回收站总占用不超过 5GB”超过后由最旧条目自动清除。我在实际使用中遇到过一次大批量清理后没有及时 purge 回收站结果回收站占掉十几 GB“清理完磁盘反而更满”的尴尬局面。所以我在自动化任务中增加了一条链式命令pkgcache-cleaner clean --keep-last 2 --min-age 7d --yes pkgcache-cleaner trash shrink --max-size 5GB先用 shrink 命令把回收站压缩到 5GB 以下再执行下一轮定时任务。这样既保证有恢复能力又不会让回收站拖累磁盘空间。6. 跑了一段时间后的实际效果与长期维护建议6.1 这台机器的磁盘从 98% 降到了 61%以我自己的主力开发机为例连续使用工具三周后磁盘占用曲线非常平稳。首次深度清理释放了大约 27GB 空间后续每周末定时清理平均每次释放 2~4GB。关键是不再有“磁盘满到构建失败”的情况。时间点磁盘剩余缓存总大小说明初次诊断8.2 GB58.7 GB磁盘接近满构建卡顿第一次深度清理35.4 GB31.5 GB释放约 27 GB一周后28.9 GB8.9 GB执行了周末温和清理三周后32.1 GB9.6 GB状态稳定不再暴涨这套自动化组合拳跑下来之后我很少再主动去看磁盘空间了。甚至有一次朋友问我“你电脑存储怎么一直这么宽裕”我直接把命令行历史和定时配置发给他。6.2 配合哪些习惯可以让磁盘长期健康工具解决的是一次性和周期性的清理问题但从根上减少缓存增长量才是长期策略。第一个习惯是给 CI 流水线配--prefer-offlinenpm 和 yarn 都支持。这样开发机在安装了相同依赖的缓存后不会重复下载完整的 tarball缓存增长率会显著下降。第二个习惯是定期做“依赖去重整理”比如 pnpm 会自动做内容寻址去重而 npm 和 yarn 需要跑npx depcheck找出不再使用的依赖并移除这能减少锁文件体积间接减少缓存对象数量。第三个习惯是给 Docker 的buildkit设--build-cache-size上限避免构建缓存无限增长。这几个习惯配合轻量级清理工具比单靠“周清理定时任务”的效果更持久。毕竟缓存体积控制住了清理压力也会小很多。6.3 后续计划及给新使用者的几句心里话这个开源项目目前大概六七千行代码核心功能都在但依然有可扩展的方向。团队正在规划的一个功能是“依赖使用热度分析”它会根据你的 git 历史更新频率计算出哪些依赖在未来三个月最可能被重新使用然后动态调整保留策略。如果这个功能稳定就会把工具的默认配置做成全自动模式真正做到“零人工参与”。最后给第一次用的开发者一句实在话清理缓存这件事不要等到磁盘满了才想起来更不要第一次就追求“全部清空”。先用默认策略跑两周观察有没有项目出现依赖缺失确认没问题之后再逐步收紧--keep-last和--min-age。我自己就是从“保守派”慢慢过渡到现在的“适度激进派”的。硬盘空间是省出来了项目稳定不能因此丢。
开发机磁盘告急？用开源工具智能清理 npm、pip 等包管理器缓存
说实话我一开始真没把磁盘空间当回事直到连续两次在本地构建大型前端项目时IDE 直接卡死系统弹窗明晃晃地告诉我“启动磁盘已满”。打开磁盘分析工具一看好家伙~/.npm、~/.cache/pip、~/Library/Caches这些目录加一起快 60GB堆的全是各种仓库包缓存。手动删了几次过两周又满而且每次删都提心吊胆生怕把正在用的依赖版本给清了。后来我们团队干脆自己写了一个开源的仓库包缓存清理工具按包管理器逐个扫描、智能判定可清理项、支持配置白名单和自动化调度。这篇博文就把这个项目的设计思路、核心机制、完整实操流程以及我们踩过的坑全部整理出来给同样被磁盘告急困扰的开发者一个可以直接抄作业的解决方案。1. 磁盘告急不是错觉开发者的缓存到底有多能吃1.1 拆开各家包管理器的缓存目录我吓一跳我见过太多同事遇到磁盘满的第一个反应是“删电影”、“删照片”结果清理完系统缓存一看真正的大头全在开发工具链里。不同语言、不同包管理器都有自己的缓存机制它们之间相互独立但有一个共同点默认不设上限只增不减。以我手头一台开发机为例逐一拆解各缓存目录的真实占用包管理器默认缓存路径实测占用为什么会这么大npm~/.npm/_cacache约 8.6GB每执行一次npm install依赖包的 tarball 和 metadata 都会缓存版本分支多时特别膨胀pip~/.cache/pip约 12.2GBpip 下载的 wheel 包全部缓存在这里多个 Python 虚拟环境共享同一份缓存pnpm~/.local/share/pnpm/store约 6.4GBpnpm 采用全局内容寻址存储虽节省了重复下载但老版本包不会被自动清理yarn~/.cache/yarn约 3.1GB原理与 npm 类似yarn v1 的缓存结构更松散Maven~/.m2/repository约 15.8GB所有历史依赖的 pom 和 jar 完整保留且不区分版本是否仍被引用Gradle~/.gradle/caches约 7.5GB包含已解析的依赖、构建缓存、转换缓存量级随项目数量线性增长Go Module$GOPATH/pkg/mod/cache约 2.3GB模块缓存与模块源码都存储在本机清理需要额外注意版本锁定的问题Rust/Cargo~/.cargo/registry约 1.8GBcrate 源码和压缩包缓存在 registry 下解压后的 src 占用更大这不是个例。如果你同时做前端、后端偶尔玩一点 Python 脚本和 Android 构建那机器上随便就能堆出 40GB 以上的缓存目录。关键问题是这些缓存目录本身设计为“安全可删”但大多数开发者并不清楚哪些是依赖缓存、哪些是项目代码、哪些是构建产物自然不敢乱动。1.2 手动清理为什么总清不干净我也尝试过手动清理路径倒是都知道但有几个痛点始终没解决。不同包管理器的清理命令不统一。npm 有npm cache clean --forcepip 是pip cache purgeyarn 是yarn cache cleanGradle 需要手动删除整个caches目录Go 的要靠go clean -modcache。每个命令的清理力度、安全边界都不一样记错就得翻文档。更麻烦的是“清理时机”问题。很多缓存清理命令是整体清除比如npm cache clean --force会把整个_cacache全删掉不留任何余地。而你本地的某个依赖版本可能只在旧项目里用到一旦被清掉下次运行旧项目就得重新下载等于把耗时换成了空间不划算。还有一类缓存非常隐蔽比如 Gradle 的构建缓存、Docker 的 overlay2 镜像层缓存、Homebrew 的下载缓存。它们分布在系统各处单靠“清理软件”或“存储分析工具”并不一定能准确识别哪些能被安全删除。这就引出了我们做这款工具的动机与其记一堆命令、人工判断不如把规则集中起来做成一个可扫描、可预览、可配置的清理工具。2. 清理工具的核心运行逻辑先扫描、再判断、后清理2.1 扫描层它到底是怎么找到缓存的别以为只是简单地遍历目录真正要安全清理必须先搞明白每个文件夹里装的是什么。我们的工具把扫描分为三个层级。第一层是静态识别。直接检查各包管理器约定的缓存路径是否存在比如~/.npm、~/.cache/pip、~/.m2/repository这一层用于快速定位和大致估算体积。第二层是元数据解析。以 npm 的_cacache为例目录里有content-v2和index-v5两个子目录里面是经过 hash 处理的二进制文件直接删文件是粗暴的做法应该借助cacache库来读取索引获取每个缓存条目对应的包名和版本号。第三层是版本关联分析。我们会扫描当前机器上所有项目的package-lock.json、pnpm-lock.yaml、pipfile.lock等锁文件构建出“当前仍在使用的版本集合”只有不在此集合中的缓存条目才被判定为可清理。这套机制的最大价值是“我删掉的确定都是没用的”。而不是简单粗暴地把缓存目录清空。以下是伪代码级别的扫描流程示例以 npm 缓存为例func scanNpmCache(cacheDir string, activeVersions map[string][]string) ([]CacheEntry, error) { entries : []CacheEntry{} // 使用 cacache 索引读取缓存条目 index, err : cacache.List(cacheDir) for entry : range index { pkgName, pkgVersion : parseCacheKey(entry.Key) if !isVersionActive(activeVersions, pkgName, pkgVersion) { entries append(entries, CacheEntry{ Path: entry.Path, Size: entry.Size, PkgName: pkgName, Version: pkgVersion, }) } } return entries, nil }扫描完后工具会生成一份详细的清理报告包含每条可清理项的名称、版本、占用体积、最后被访问时间。开发者可以先看报告确认无误后再执行清理。2.2 判定策略哪些缓存能删哪些不能动这是整个工具的灵魂。我见过很多“存储清理工具”把缓存目录整个标记为“可删除”使用体验确实粗暴误删风险也极高。我们的工具把这些缓存分成四类每一类采用不同的判定策略。第一类是无条件可清理缓存。典型的是构建过程产生的临时文件比如 Gradle 的transforms-*目录、pip 解压后的临时目录这类缓存即使删掉也不会影响任何已安装的依赖只是下次构建时会重新生成。这类条目会直接进入可清理列表。第二类是按版本保留缓存。以 Maven 的~/.m2/repository为例工具会解析当前机器所有 Maven 项目pom.xml以及gradle.lockfile实际引用的版本把未被引用的旧版本加入清理列表。同时提供一个“保留最近 N 个版本”的选项防止切分支时频繁重新下载。第三类是时间阈值缓存。npm 和 pip 这类缓存支持记录最后访问时间我们可以设置一个阈值比如“30 天内没有访问过的缓存才清理”。默认清理时不会动最近使用过的包保证开发体验。第四类是需要人工确认的重点关注缓存。比如 Go module 缓存如果你同时维护多个 Go 项目且使用了本地replace指令模块缓存里的源码可能被项目直接引用这时候自动删除是有风险的。工具会把这一类单独在报告中标注“建议手动确认”默认不勾选。2.3 安全保护删错了也能救回来即便是设计了这么细的判定策略依然会遇到边界情况。我们干脆给工具加了回收站机制。清理动作不是直接rm -rf而是先把待删除文件移动到一个隐藏的回收目录比如~/.pkgcache-cleaner/trash/并记录一份 JSON 格式的元数据原始路径、删除时间、所属包管理器。如果开发者在清理后发现自己本地某个项目依赖缺失可以用pkgcache-cleaner restore entry-id一键恢复。同时工具的默认配置遵循“先预览后执行”的安全模式。执行清理命令时如果没有显式添加--yes参数工具只会输出清理计划和预计释放空间不会做任何破坏性操作。这个设计在我后续接 CI/CD 定时任务时帮了大忙后面细说。3. 从零上手安装、首次扫描与一次安全清理3.1 安装方式与运行环境工具目前支持三大主流平台Linuxx86_64/arm64、macOSApple Silicon 与 Intel、Windows通过 WSL 或者原生二进制。安装方式我推荐直接使用预编译二进制不依赖额外的运行时也不污染全局环境。# Linux / macOS curl -fsSL https://pkgcache-cleaner.example.com/install.sh | sh # macOS 也可以通过 Homebrew brew tap pkgcache-cleaner/tap brew install pkgcache-cleaner # Windows使用 scoop scoop bucket add pkgcache https://pkgcache-cleaner.example.com/scoop-bucket scoop install pkgcache-cleaner代码仓库里的源码编译也很简单核心逻辑用 Go 编写一个二进制文件搞定。为什么要用 Go一个重要原因是它编译出的静态二进制不依赖 glibc 版本放哪都能跑另一个原因是 Go 标准库的filepath.Walk和并发控制写起来顺手扫描几十 GB 目录时能达到不错的吞吐。3.2 第一次扫描不要急着删先看报告装好之后直接执行pkgcache-cleaner scan这条命令会扫描所有已识别的包管理器缓存并在终端输出类似这样的汇总表格Scanning... 共发现 6 个可扫描的缓存目录 --------------------------------------------------------------------------------------------- | 包管理器 | 缓存路径 | 扫描结果 | --------------------------------------------------------------------------------------------- | npm | /home/user/.npm/_cacache | 8.6 GB | | pip | /home/user/.cache/pip | 12.2 GB | | pnpm | /home/user/.local/share/pnpm/store | 6.4 GB | | maven | /home/user/.m2/repository | 15.8 GB | | gradle | /home/user/.gradle/caches | 7.5 GB | | cargo | /home/user/.cargo/registry | 1.2 GB | ---------------------------------------------------------------------------------------------扫描之后生成完整的可清理候选列表并按“预计释放空间”排序的前 20 条会展示出来。每条数据都标注了包名、版本、缓存路径和体积让你清楚自己即将删掉的是什么。这里必须强调第一次使用请务必执行pkgcache-cleaner scan --report/tmp/clean-report.json把完整报告导出来打开看一眼。尤其是 Maven 和 Gradle 的部分确认里面列出的“可清理版本”确实没有你正在维护的项目的依赖然后再进入下一步。3.3 执行清理并设定保留策略预览确认没问题后我一般会加上一个保留策略参数再执行pkgcache-cleaner clean --keep-last 3 --min-age 30d --yes参数含义很简单--keep-last 3对于同一包名的多个历史版本只保留最近 3 个版本其余清理--min-age 30d只清理最后访问时间超过 30 天的缓存项--yes跳过交互确认直接执行这条命令跑完后工具会打印释放空间统计并列出所有被移动进回收站的条目数量和总大小。如果需要从回收站恢复pkgcache-cleaner list-trash pkgcache-cleaner restore entry-id最让我放心的是restore会依据元数据把文件原样放回原路径即使是符号链接或较长的嵌套目录也能还原。当然回收站里的文件也会占用磁盘空间所以工具提供了trash purge命令确认一段时间内没有异常后手动清除。4. 自动化实践定时清理与 CI 场景下的磁盘瘦身4.1 配置定时任务给开发机设置清理周期开发机上缓存增长的速度远比想象中快。尤其是每天要拉多个分支、频繁切换版本的同学缓存会呈现指数级累积趋势。手动想起才清理一次完全跟不上节奏。我现在的习惯是在每台开发机上配置两个定时任务一个“温和清理”每周执行一次一个“深度清理”每月执行一次。linux 上用 cronmacOS 上我用 launchd配置方式如下# 每周末凌晨 3 点执行温和清理 0 3 * * 0 /usr/local/bin/pkgcache-cleaner clean --keep-last 2 --min-age 7d --yes /var/log/pkgcache-cleaner.log 21如果你用的是 macOS 的 launchd可以写一个简单的 plist 文件放到~/Library/LaunchAgents/下再用launchctl load加载。这里有一个小细节定时任务里必须使用绝对路径因为 launchd 和 cron 的环境 PATH 通常不包含pkgcache-cleaner所在的目录我最初就吃过这个亏任务静默失败了两周。4.2 在 CI Runner 上给构建缓存做“瘦身”CI 流水线里仓库包缓存工具的用武之地比本地还大。GitHub Actions 的缓存actions/cache、自建 GitLab Runner 的 Maven/Gradle 缓存一旦不清理几十 GB 的磁盘很容易在几周内被耗光。我使用的方式是在 CI 流程末尾加一步“回收磁盘空间”- name: Clean caches run: | pkgcache-cleaner clean \ --keep-last 2 \ --min-age 3d \ --allowed-managers npm,pip,maven,gradle \ --yes--allowed-managers参数很关键它限制只处理指定的包管理器缓存避免误伤容器镜像或系统包缓存。如果 Runner 是用 Docker 容器跑的那还需要留意挂载目录的权限一般建议将pkgcache-cleaner安装在 Runner 宿主机的/usr/local/bin下通过宿主机 cron 定时清理而不是在流水线里直接删挂在容器里的目录原因在于容器内的删除操作对 overlay 文件系统上的文件并不会真正释放宿主机块。4.3 多机器批量管理的配置同步方案当团队里有 5 台以上开发机或几十台 CI Runner 时逐台机器手敲命令就不现实了。我们的解法是把工具默认配置抽离成一个 YAML 文件集中管理通过 Ansible 或自定义脚本下发给各台机器。配置文件大致长这样strategy: keep_last: 3 min_age_days: 30 scan_depth: full managers: npm: enabled: true extra_paths: [] pip: enabled: true maven: enabled: true keep_versions_by_package: 3 gradle: enabled: true go: enabled: false # Go 模块缓存默认不自动清 protect: paths: - /data/ci-cache/maven-repo # 这里指定永远不清的目录 log_level: info配置文件通过/etc/pkgcache-cleaner/config.ymlLinux或~/Library/Application Support/pkgcache-cleaner/config.ymlmacOS读取。这样即使每个人手动调用工具也用同一套策略。5. 实战中踩过的坑及对应的修复方案5.1 把 pip 缓存当垃圾清掉后离线安装失败了这是我自己踩得最惨的一次。团队某台 CI Runner 出于安全要求不能连外网所有 Python 依赖只能通过内网 PyPI 镜像下载同时本地保留一份“离线缓存包”。原本工具的策略是保留所有 pip 缓存但有一次我为了给Runner 腾空间临时手动改了配置把--min-age设成了0d结果把离线依赖缓存全打进了回收站。等流水线跑起来才发现需要离线安装的包一个都没有流水线全部失败。后来我在配置里加了两个保护机制一是在protect.paths中明确列出离线缓存目录二是为关键包管理器单独设一个allow_clean: false开关。对大多数开发者来说把“公司内部专用的离线 wheel 目录”或“特定项目的 vendor 目录”列为受保护路径是很有必要的。5.2 权限不够导致 Gradle 缓存清理失败还差点报警Gradle 缓存目录的文件属主不一定是当前用户尤其是当多个开发账号共用同一台机器或用sudo跑过 Gradle 构建时。用普通用户执行清理部分文件会因permission denied失败但直接sudo pkgcache-cleaner又可能把回收站的元数据写到 root 目录下导致普通用户后续无法执行restore。建议的解决方式是先用普通用户身份跑scan识别出需要清理但无权限的目录再单独用sudo pkgcache-cleaner clean --targets /home/user/.gradle/caches --yes处理。工具在无权限清理时的处理策略是跳过并继续而不是中断整个任务这样至少能先释放大部分空间。不过要注意涉及用户级缓存的清理最好还是在目标用户自己的会话下执行避免权限混乱。5.3 清理 Docker 缓存时不能只盯着/var/lib/dockerDocker 的镜像层、构建缓存和 overlay2 目录往往比包管理器缓存更占空间。标题虽然说的是“仓库包缓存”但实际开发者的磁盘告急通常是多个源头叠加的结果。我们把 Docker 的缓存识别做了扩展/var/lib/docker下的buildkit构建缓存、容器运行后残留的 overlay2 目录以及docker system prune命令能释放的那部分空间都会单独列出。实际处理有一个主次关系先用包管理器清理工具释放本机包缓存再执行docker system prune -f清理悬空镜像和构建缓存。后者对运行中的容器是安全的不会伤到正在使用的镜像层。5.4 误删后的恢复回收站不是保险箱有容量上限回收站机制虽好但内部有一个容量上限。默认配置是“回收站总占用不超过 5GB”超过后由最旧条目自动清除。我在实际使用中遇到过一次大批量清理后没有及时 purge 回收站结果回收站占掉十几 GB“清理完磁盘反而更满”的尴尬局面。所以我在自动化任务中增加了一条链式命令pkgcache-cleaner clean --keep-last 2 --min-age 7d --yes pkgcache-cleaner trash shrink --max-size 5GB先用 shrink 命令把回收站压缩到 5GB 以下再执行下一轮定时任务。这样既保证有恢复能力又不会让回收站拖累磁盘空间。6. 跑了一段时间后的实际效果与长期维护建议6.1 这台机器的磁盘从 98% 降到了 61%以我自己的主力开发机为例连续使用工具三周后磁盘占用曲线非常平稳。首次深度清理释放了大约 27GB 空间后续每周末定时清理平均每次释放 2~4GB。关键是不再有“磁盘满到构建失败”的情况。时间点磁盘剩余缓存总大小说明初次诊断8.2 GB58.7 GB磁盘接近满构建卡顿第一次深度清理35.4 GB31.5 GB释放约 27 GB一周后28.9 GB8.9 GB执行了周末温和清理三周后32.1 GB9.6 GB状态稳定不再暴涨这套自动化组合拳跑下来之后我很少再主动去看磁盘空间了。甚至有一次朋友问我“你电脑存储怎么一直这么宽裕”我直接把命令行历史和定时配置发给他。6.2 配合哪些习惯可以让磁盘长期健康工具解决的是一次性和周期性的清理问题但从根上减少缓存增长量才是长期策略。第一个习惯是给 CI 流水线配--prefer-offlinenpm 和 yarn 都支持。这样开发机在安装了相同依赖的缓存后不会重复下载完整的 tarball缓存增长率会显著下降。第二个习惯是定期做“依赖去重整理”比如 pnpm 会自动做内容寻址去重而 npm 和 yarn 需要跑npx depcheck找出不再使用的依赖并移除这能减少锁文件体积间接减少缓存对象数量。第三个习惯是给 Docker 的buildkit设--build-cache-size上限避免构建缓存无限增长。这几个习惯配合轻量级清理工具比单靠“周清理定时任务”的效果更持久。毕竟缓存体积控制住了清理压力也会小很多。6.3 后续计划及给新使用者的几句心里话这个开源项目目前大概六七千行代码核心功能都在但依然有可扩展的方向。团队正在规划的一个功能是“依赖使用热度分析”它会根据你的 git 历史更新频率计算出哪些依赖在未来三个月最可能被重新使用然后动态调整保留策略。如果这个功能稳定就会把工具的默认配置做成全自动模式真正做到“零人工参与”。最后给第一次用的开发者一句实在话清理缓存这件事不要等到磁盘满了才想起来更不要第一次就追求“全部清空”。先用默认策略跑两周观察有没有项目出现依赖缺失确认没问题之后再逐步收紧--keep-last和--min-age。我自己就是从“保守派”慢慢过渡到现在的“适度激进派”的。硬盘空间是省出来了项目稳定不能因此丢。
` 方法：按选择器反向过滤节点的完整指南)
代码包深度解析与实践指南)
