我有个不算好的习惯写代码写着写着就会看一眼系统盘剩余空间。不是强迫症纯粹是被各种临时文件坑怕了。尤其是同时开着 JetBrains 全家桶、VS Code、Docker 和几个小程序开发者工具的时候三两天不管几十 GB 就像被啃掉一样。市面上很多临时文件清理工具要么只会清系统垃圾要么一键“加速”乱删一通删完项目打不开的场面我见过太多次了。所以后来我干脆按照自己的开发场景写了一个面向开发者、以安全为第一原则的临时文件清理小工具。这篇就当一次完整复盘它是怎么设计的、核心逻辑怎么实现、实际用下来踩过哪些坑都会讲清楚。如果你也被磁盘占用和误删风险反复折磨这篇应该能帮上忙。1. 临时文件从哪里来先搞清楚清理对象开发者的临时文件和普通用户理解的“系统垃圾”不是一个概念。普通清理软件关注的是 IE 缓存、旧更新补丁、回收站残留可开发者真正头疼的是另一批东西IDE 索引、包管理器缓存、构建中间产物、调试日志、模拟器快照。如果不先搞清楚这些文件的生成机制就谈不上“智能清理”更谈不上安全。1.1 IDE 缓存看着不显眼攒起来吓人JetBrains 系工具的索引缓存是个典型。IDEA、PyCharm、WebStorm 都会在~/.cache/JetBrains下面给每个项目建索引你打开的项目越多、版本升级越频繁这个目录就越大。我见过一台只装了 IDEA 和 PyCharm 的机器这个目录涨到 20 多 GB 还不自知。VS Code 的 Cache 目录、Cursor 的索引日志也差不多只是没那么夸张。这类缓存的作用是加速搜索和跳转删除后最坏的结果是重新索引一遍项目本身完全不受影响。所以 IDE 历史缓存属于清理优先级最高的一档。但有一点要注意旧版 IDE 的缓存会集中放在按版本命名的目录里比如IntelliJIdea2024.3和IntelliJIdea2025.1清理时最好保留当前主力版本的缓存只处理历史版本和几个月没打开的老项目索引。1.2 包管理器与构建工具缓存删了未必更快npm、pnpm、pip、Gradle、Maven 这些工具都会往本地缓存里塞东西。npm 默认把下载过的包存在~/.npm/_cacachepnpm 有自己的全局内容寻址存储pip 的缓存通常在~/.cache/pipGradle 则是~/.gradle/caches。这些缓存的设计初衷都是“别让开发者在同一份依赖上反复下载”所以它们体积膨胀得很快但也真的有用。这里就引出一个许多清理工具没想明白的问题缓存不全是垃圾。离线环境下要重新装一套依赖npm 缓存和 pip 缓存可能就是救命稻草Gradle 缓存删掉之后下一次构建要重新下载全部依赖CI 耗时可能从三分钟变成三十分钟。所以我的工具里这类目录被归到“谨慎清理”而不是“安全清理”档位默认只做清扫和压缩不搞一刀切。1.3 项目内的构建产物与运行痕迹每个项目本身也在制造临时文件。前端项目的dist、.nuxt、.nextJava 工程的targetPython 项目的__pycache__Android 工程的build还有小程序开发里常见unpackage目录这些本质上都是可再生产物。它们占的地方不小删掉之后重新构建就能再生成对源码仓库没有风险。另外一类容易被忽略的是 iOS/Android 调试过程中留下的崩溃日志、模拟器临时快照、ADB 的 logcat 日志文件。比如你开着 Android 模拟器调试 App~/.android下会产生大量临时数据和快照做小程序的用微信开发者工具跑项目会在应用缓存目录里留下一堆中间编译文件。这类文件往往被系统清理工具漏掉在开发者自己写工具之前几乎没人管。1.4 为什么不能直接全删很多人觉得“既然是临时文件全删不就行了”。这个想法在开发环境里非常危险。第一包管理器的缓存和依赖实际是联动关系pnpm 的 store 目录一旦被粗暴删除项目里引用到的符号链接就会断裂到时候不是省几十 GB 的问题是所有项目都打不开。第二有些日志是排查线上问题的关键证据删了之后出了问题根本无从下手。第三IDE 缓存虽然可再生但删除正在运行的 IDE 的索引缓存可能导致编辑器卡顿一整天。所以真正合理的策略是把文件按安全等级分类让用户决定哪些可以自动清、哪些需要人工确认而不是让工具替你拍板。2. 工具的设计思路不追求删得狠追求删得准动手写这个工具之前我先给自己定了几条原则。这些原则后来证明比具体代码值钱得多也直接决定了它和市面上一键清理软件的根本区别。2.1 先扫描再预览最后才动手没有预览的清理工具都是耍流氓。很多软件弹一个“发现垃圾文件 5.2GB”然后让你点“一键清理”你根本不知道这 5.2GB 里装的是什么、删了会不会影响某个正在开发的项目。我给自己写的工具强制要求必须先进入扫描模式把所有匹配规则的目录、文件大小、风险等级全部列出来用户确认之后才允许进入清理模式。预览的意义不光是“知会”更是给人一个重新判断的机会。实际操作里扫描模式还有一个隐藏好处它能反向暴露你项目里的异常膨胀点。有一次我扫完发现一个老 Vue 项目的node_modules占了 4 个多 GB但同级别的其他项目只有几百 MB循着这个线索追下去才发现是依赖版本冲突导致的重复安装这已经不是清理临时文件的问题了而是工程化习惯的问题。2.2 三级风险分类制度我把所有的可清理目标分成三个档位每个档位的处理方式完全不同风险等级典型对象默认处理方式安全IDE 历史索引、__pycache__、构建产物目录可自动清理移动到回收区谨慎npm/pip/Gradle/Docker 缓存需人工确认或按保留天数清理不建议正在运行的进程日志、项目依赖目录、系统目录默认跳过除非强制指定这个分类决定了工具的第一行为逻辑。比如你执行的是--level safe它只会碰第一档的目录绝对不会顺手把~/.npm给删了如果想清理包管理器缓存必须单独显式指定--level caution并且工具会在命令行里再次打印确认清单。宁可让用户多敲一次回车也不能让他为一次误删买单。2.3 白名单与黑名单机制规则匹配再精确也不可能覆盖所有用户的特殊习惯。所以工具支持白名单和黑名单。黑名单表示“即使匹配了规则也绝对不许碰”白名单表示“即使不匹配通用规则也要纳入清理候选”。举个例子我有个同事用 Flutter 开发他的项目里有个build目录正常情况下安全档位会把这个目录识别为可清理产物但那个目录实际上是他自己写的、依赖外部数据的插件编译缓存删了就得重新配置环境。这时候一条黑名单规则就能保住它。黑名单的优先级永远高于扫描规则。这个设计很像防火墙的默认拒绝策略没有明确允许的就不准动。早期版本我没加这个机制结果差点把同事正运行的服务目录给清了后来黑名单就成了所有规则执行前的最后一道防线。2.4 权限和明示意识我特别反感工具越权操作。现在很多 App 在申请权限的时候会明确写“开发者将在获取你的明示同意后使用你的相册仅写入权限用途是保存调试截图”这种明示才是正规做法。清理工具也一样它要动你的文件系统就必须在动手之前把“将要删除哪些路径、删除后有什么后果、回收区在哪里”全部摆到台面上。所以这个工具里根本没有隐藏的“后台自动清理”功能。就算设置了定时任务它也只是定时把扫描结果写到日志文件里真正执行删除还是需要走一遍清理命令。这个设计牺牲了一点便利性但换来了长期的稳定和安全。2.5 为什么不做“一键清理”按钮不止一个人建议我给工具加个“一键清理”理由是用户喜欢简单。但我一直没加。开发环境太复杂了同一个路径在不同人机器上含义都不同build目录在 Java 工程里是源码编译输出在某个测试工程里可能是手工维护的基准数据“缓存”在某些工具里是可以删除的在某些工具里是维持运行状态的核心数据。一旦做成一键清理就相当于把风险判断的责任全部转交给用户而出问题之后买单的也是用户。对开发者来说效率固然重要但可预测、可回退比“看起来快”重要得多。3. 核心实现拆解一个 Python 清理器就够了工具本身没有用什么高深的技术就是 Python 标准库加一个命令行入口整体代码量控制在几百行以内。选 Python 纯粹是因为跨平台好写、用户也好改不需要编译环境扔到任何一台电脑上只要装了 Python 3 就能跑。3.1 目录扫描函数不跟随软链接避免循环清理工具的第一件事是计算目录大小。这里有一个非常容易踩坑的点如果目录里存在指向父目录的符号链接递归遍历会陷入死循环。所以扫描函数必须默认不跟随符号链接。import os def dir_size(path: str, follow_symlinks: bool False) - int: total 0 try: with os.scandir(path) as it: for entry in it: if entry.is_symlink() and not follow_symlinks: # 优先跳过符号链接防止循环目录 continue if entry.is_dir(follow_symlinksfollow_symlinks): total dir_size(entry.path, follow_symlinks) elif entry.is_file(follow_symlinksfollow_symlinks): try: total entry.stat(follow_symlinksfollow_symlinks).st_size except OSError: pass except OSError: # 遇到权限不足的目录跳过而不是报错 pass return total这段逻辑里有几个细节用os.scandir而不是os.listdir因为它能复用目录项信息少一次额外系统调用遍历时对每个文件单独捕获OSError避免因为单个文件失去权限导致整个扫描中断最多只跟踪一层目录不处理“目录内还有指向外部目录的链接”的情况这是出于安全考虑——清理工具不该跟着符号链接跑到项目目录之外去删东西。3.2 规则文件用 JSON 描述清理目标扫描目标不能写死在代码里否则用户每换一个开发场景就得改程序。我用的办法是规则文件默认读取一份rules.json里面按风险等级定义清理对象。{ safe: { jetbrains_index: [~/.cache/JetBrains/**], python_cache: [**/__pycache__, **/*.pyc], build_output: [**/build, **/dist, **/target], unpackage: [**/unpackage/**] }, caution: { npm_cache: [~/.npm/_cacache, ~/AppData/Local/npm-cache], pip_cache: [~/.cache/pip, ~/Library/Caches/pip], gradle_cache: [~/.gradle/caches], docker_build_cache: [~/.docker/buildx, /var/lib/docker] } }规则匹配用的是fnmatch风格通配符**表示递归任意层级*表示当前层级的任意文件名。~会在运行时统一展开成用户主目录这样同一个规则文件在 Windows、macOS、Linux 上都能用区别只是路径前缀不一样。用户完全可以在此基础上补充自己的目录比如把微信开发者工具的User Data缓存目录加进去或者把某个私有多余的临时盘目录加进白名单。3.3 安全删除先移入回收区不直接删除这是整个工具里我认为最值得借鉴的一个设计。清理文件时默认不执行真正意义上的删除而是把所有目标目录移动到用户主目录下隐藏的回收区比如~/.cache-cleaner/trash/20250618-153000/。等到确认项目没有异常再手动清空回收区。这个思路相当于给所有删除操作加了一层后悔药误删之后还有机会找回来。import os import shutil import time def move_to_trash(paths, trash_root~/.cache-cleaner/trash): trash_root os.path.expanduser(trash_root) trash_dir os.path.join(trash_root, time.strftime(%Y%m%d-%H%M%S)) os.makedirs(trash_dir, exist_okTrue) for p in paths: if not os.path.exists(p): continue target os.path.join(trash_dir, os.path.basename(p.rstrip(os.sep))) if os.path.exists(target): target f-{len(os.listdir(trash_dir))} shutil.move(p, target)移动操作比物理删除慢但非常值得。跨磁盘分区时shutil.move会先复制再删除原目录碰到几个 GB 的 gradle 缓存可能需要一段时间所以我会在命令行输出里显示每个目录的移动进度。如果只是清理几百 MB 的__pycache__这个耗时几乎可以忽略。3.4 命令行入口明确、克制、可预测整个工具的命令行设计遵循“少即是多”只有三个核心动作# 只扫描不删除输出详细分类清单 python cleaner.py --scan # 安全档清理只处理 safe 列表里的目录 python cleaner.py --clean --level safe # 清理前先打印将要移动的完整路径并列出回收区位置 python cleaner.py --clean --level caution --dry-run--dry-run这个参数是我后来补的作用是和--scan类似但走完整的清理逻辑唯一的区别是不真正执行shutil.move。它的意义在于能让用户看到“如果我执行清理每个目录会去哪里”避免清理逻辑和扫描逻辑因为代码差异产生不一致。这个细节看着不起眼但在自动化脚本里极其重要。4. 实战操作指南从首次扫描到定时清理工具写完之后我在自己的 MacBook、Windows 开发机和一台 Linux 服务器上分别跑了一个多月逐步打磨出了一套可复用的操作流程。下面就是完整的实战路径。4.1 第一次扫描先看清楚空间都去哪了拿到工具的第一件事不是清理而是扫描。我第一次跑扫描时结果给自己看愣了示例扫描结果部分分类路径占用风险等级JetBrains 索引~/.cache/JetBrains23.6 GB安全pip 缓存~/.cache/pip8.1 GB谨慎gradle 缓存~/.gradle/caches12.4 GB谨慎Python 字节码各项目pycache620 MB安全npm 缓存~/.npm/_cacache5.2 GB谨慎微信开发者工具缓存~/Library/Application Support/微信开发者工具4.8 GB谨慎很多人的第一反应是“全删掉”。但按前面的分类原则我不建议这么做。JetBrains 索引虽然属于安全级但如果你手头还有几个项目在主力使用删除当前版本的索引会让 IDE 重新建立索引反而影响写代码。更稳妥的做法是只清理旧版本 IDE 的索引目录保留当前版本的缓存。对于 npm、pip、gradle 这类包管理器缓存先不急着清理可以等构建环境稳定之后再集中处理。4.2 按场景逐个处理而不是一把梭第一个建议是优先使用官方提供的手段清理包管理器缓存而不是直接用清理工具删目录。npm 推荐用npm cache verify它会把不可用的缓存数据清掉但保留仍然有效的包如果确认不需要缓存了再执行npm cache clean --force。pnpm 用户要用pnpm store prune它会安全地移除所有项目不再引用的 store 对象比手动删 store 目录安全太多。pip 对应的是pip cache purge。Docker 更特殊它的大头不一定在当前用户目录下而是在/var/lib/docker普通工具扫不到而且镜像层是共享的直接删目录极大概率导致 Docker 损坏。正确做法是先用docker system df看每一类资源占用情况docker system df docker builder prune --filter until720h -f第二条命令会清理 30 天前产生的构建缓存属于相对温和的操作。如果你确认不需要保留任何未使用的镜像可以用docker system prune -a但这个命令要非常谨慎它会移除所有没有被容器引用的镜像一旦误删下次部署就要全部重新拉取。小程序和跨端开发这块微信开发者工具会在本地缓存编译产物和用户数据清理前一定要先完全退出工具进程否则缓存目录被占用会导致移动失败。uniapp 项目大多会在本地生成unpackage目录这是可再生的构建产物属于安全档只要确定当前项目没有正在运行的调试会话就可以放心清。HBuilderX 的编译缓存位置在不同系统上差异很大大家不要依赖网上的固定路径建议先跑扫描结果再决定要不要纳入规则。4.3 设置定时清理让工具进入常态化清理工具最大的价值不是“用的时候帮你删一次”而是“让它帮你盯住磁盘不被悄悄填满”。我在 Linux 服务器上用的 crontab 大致长这样0 3 * * 0 cd /opt/cleaner /usr/bin/python3 cleaner.py --clean --level safe --keep-days 30 /var/log/cleaner.log 21每周日凌晨三点自动执行一次安全档清理目标目录里距离现在超过 30 天的回收区内容会被一并清空。--keep-days 30是一个关键参数它让工具不会把最近一个月的包管理器缓存全部干掉给离线安装留出缓冲。Windows 上可以通过任务计划程序实现同样效果macOS 则可以用 launchd。CI 环境里也可以挂类似的清理策略。比如 GitHub Actions 的 runner 磁盘空间经常告急在 workflow 里加一步- name: Clean pip and go cache run: | pip cache purge go clean -cache df -h这里的重点同样是“别清过头”。CI 的缓存机制对构建加速很重要如果每次构建都清空等于故意降低效率。我的经验是只清理明确不再需要的包管理器缓存保留当前分支依赖对应的缓存目录这需要在不同的流水线里分别验证策略。4.4 规则文件版本化让团队共享清理策略工具用稳定之后我顺手把rules.json放进了 Git 仓库。这样每个成员都可以通过 PR 提交新的清理路径比如运维同学加一个日志目录前端同学加一个 Vite 缓存目录改动都会被记录在案。团队协作的收益很快体现出来大家机器上出现了相同的问题一套规则就能统一解决。规则文件版本化的另一个好处是回滚方便。如果你发现某个规则误伤了你自己的目录直接切到上一个版本再跑一次扫描就能恢复到稳定状态不需要从记忆里拼凑哪些目录该被跳过。这比任何“智能”都实在。5. 常见问题与排查实录那些被误删的瞬间工具写出来之后我在本地用了很久也把它分给十几个同事测试。每一次误删或者删不干净都是一次规则改进的机会。下面这几条是最典型的坑。5.1 清完 npm 缓存离线开发直接翻车一位同事在某内网开发环境里跑完清理第二天要搭建一个新项目发现 npm install 因为网络隔离直接失败。查了半天才发现问题是前一天的清理把~/.npm/_cacache整个干掉了本可以命中的本地缓存全都不存在安装流程被迫重新走网络而内网环境根本没有外网。这个问题的根源是清理工具把“谨慎”档位的目录和“安全”档位的目录混在了同一个命令里。后来我明确区分了档位并且把npm cache verify作为首选方案只有用户在收到警告后仍然显式要求强制清理才会执行clean --force。从这次之后我也开始要求工具在删除前统计缓存最近 30 天内是否有被读取过如果缓存仍处于活跃状态就暂停清理。5.2 “安全”分类把正在运行的依赖目录清掉了早期版本里我把build归为安全产物结果有次清理把另一个服务正在使用的编译输出目录移走了运行中的进程虽然没立刻崩但下一次发布时直接找不到产物排查了很久才发现是被移动到了回收区。解决方案是黑名单机制和进程占用检测双管齐下。黑名单保证用户明确不想清理的目录永远不会被匹配进程占用检测则是在删除前检查目录内是否有文件被进程打开如果有就单独列出来询问用户。这个功能在 Windows 上尤其重要Windows 的文件锁机制比 Linux 严格得多经常出现“明明只是个缓存目录却被服务进程占用导致删除失败”的情况。5.3 清理后空间没变Docker 层没有算进来我在跑清理工具之后发现磁盘占用并没有明显下降反复排查之下才发现真正的大头是 Docker 的 overlay2 存储层它在/var/lib/docker下面普通用户模式扫不到而且直接扫也不合适——Docker 的镜像层是共享的计入一个目录的实际大小很容易重复计算。正确的姿势是用 Docker 自己的指标工具docker system df docker image ls -f danglingtrue docker builder prune -f容器运行时留下的可写层、悬挂镜像、构建缓存这些用docker system prune才能安全回收。第三方清理工具几乎没有能力正确处理这些内容所以不如直接把它让位给 Docker 原生命令。5.4 Windows 下文件被占用移动失败怎么办Windows 上最典型的失败是shutil.move抛异常文件正由另一个进程使用。原因是 IDE 或者 Node 服务还在后台运行目录里的文件处于锁状态。我最初的处理方式是直接报错退出后来改成“跳过被锁目录并汇总报告”同时鼓励用户在清理前先关闭常见开发进程。5.5 权限导致的坑/tmp目录在 Linux 上人人都写但清理它不等于删除所有文件。正在运行的服务可能在/tmp下创建临时套接字文件或锁文件删掉之后服务状态会乱。所以工具的“不建议”档位里包含了/tmp除非用户显式指定否则绝对不会清理。另一个权限问题是清理工具如果经常要用sudo跑风险会成倍增加——sudo 模式下黑名单和白名单的过滤逻辑一旦有漏洞后果就是整个系统文件被移动。我给自己立了条规矩清理工具永远不用 sudo 执行涉及系统目录的清理一律手动用系统原生命令处理。问题现象根本原因解决方案清理后离线安装依赖失败包管理器缓存被强制清空使用官方 prune 命令或加保留天数正在运行的项目被破坏规则匹配过宽未覆盖运行时目录增加黑名单和进程占用检测清理完空间没有明显变化Docker 层未被正确统计改用 docker system df 单独处理删除失败提示文件占用开发进程未退出先关闭 IDE/服务再执行清理定时任务总是不生效环境变量或用户主目录上下文不对在 cron 里写绝对路径确认用户身份在我个人实际使用中这个清理工具最大的价值不是每次腾出多少 GB而是让我养成了每隔几天就看一下磁盘分布的习惯。规则文件、回收区、黑名单这些设计都是围绕“可回退”三个字展开的。工具再聪明也不如使用者保持一份谨慎。如果你也准备写一个类似的工具我的建议很简单先想清楚哪些目录绝对不要碰再决定哪些目录可以自动处理最后才去考虑怎么删得更快。顺序一旦搞反所谓的“临时文件清理神器”就会变成“删库神器”。