Cursor 把 C 盘吃掉 20GB？用 Python 开源工具 cursor-clean 一键清理

1. Cursor 缓存膨胀把 C 盘吃满的真实场景如果你在 Windows 上用 Cursor 写代码超过半年大概率会遇到一个很反直觉的问题项目代码才几百 MBC 盘却莫名其妙少了十几 GB。打开「此电脑」一看系统盘飘红Windows 更新都装不下。很多人第一反应是去删node_modules、清npm cache、卸载不用的软件折腾一圈发现根本没释放多少空间。真正的大头藏在用户目录里。你可以按Win R输入下面这个路径直接跳过去%APPDATA%\Cursor展开后通常是C:\Users\你的用户名\AppData\Roaming\Cursor。用 WizTree 或者 TreeSize Free 扫一下这个目录你会看到几个体积夸张的文件和文件夹。我实测过一台用了 8 个月的机器这个目录接近 20GB拆开看主要是这么几块内容大约占用是什么state.vscdb~11GB本地状态库聊天、Agent、Composer 历史state.vscdb.backup~4GB上面那个库的备份cursor-agent多版本~2GB历史版本的 Agent CLI 安装包CachedData、logs等少量缓存和日志结论很清楚不是你的项目文件占空间是 Cursor 自己把聊天记录和 Agent 历史越堆越多。几个月前的对话对你基本没用但它一直躺在 SSD 里。官方设置里又没有「只保留最近 90 天」这种开关手动去删又怕把配置搞坏。这就是cursor-clean要解决的问题。它是一个轻量 Python 命令行工具专门扫描 Cursor 的 Roaming 目录告诉你哪些能删、哪些该留然后按你的策略清理。适合谁用所有在 Windows 上用 Cursor、C 盘开始告急的开发者。不需要你懂 SQLite也不需要你手动去翻目录装完就能跑。下面我会从定位大文件目录开始一步步带你装好、扫描、清理最后用磁盘占用对比验证效果。整个过程可复制跟着做就行。2. 用 cursor-clean 定位并清理 Cursor 大文件目录在动手清理之前先理解cursor-clean的设计思路这样你用起来才放心。它的逻辑非常朴素扫描 Cursor 的 Roaming 目录识别出三类可以安全处理的目标然后交给你确认。第一类是state.vscdb里的历史记录。这是 Cursor 的本地状态库用 SQLite 存储聊天、Agent、Composer 的历史都塞在里面。cursor-clean默认只保留最近 90 天的记录更早的会被清掉。这个天数可以通过--keep-days参数改比如你只想留 60 天就传 60。第二类是旧的cursor-agent版本。Cursor 的 Agent CLI 每次更新都会装一份新的旧版本不会自动删。工具的策略是只保留最新一份其余删掉。第三类是state.vscdb.backup。这个是备份文件工具默认不删保留着以防万一。如果你确认不需要可以自己手动处理。它有几个我比较认可的点零第三方依赖只用 Python 标准库不建自己的数据库支持中文和英文界面先扫描再确认避免误删。技术栈就是「扫目录 改 Cursor 自己的 state.vscdb 删旧文件夹」逻辑简单到你可以自己审计源码。安装方式有两种。最省事的是从 PyPI 装pip install -U cursor-clean如果你网络环境访问 PyPI 慢也可以用国内镜像pip install -U cursor-clean -i https://pypi.tuna.tsinghua.edu.cn/simple装完之后验证一下cursor-clean --version能打印出版本号就说明装好了。环境要求是 Windows Python 3.9 及以上。如果你还没装 Python去 python.org 下个 3.11 或 3.12 都行安装时记得勾选「Add Python to PATH」。这里有个前置动作必须强调清理前先完全退出 Cursor。不是关窗口是去任务管理器里确认没有Cursor.exe进程。因为工具要压缩 SQLite 数据库如果 Cursor 还开着占用文件压缩可能卡住甚至损坏。按Ctrl Shift Esc打开任务管理器在「进程」里找 Cursor全部结束任务。退出之后先跑扫描看看能清什么cursor-clean scan --lang zh--lang zh是让输出用中文不加就是英文。扫描是只读操作不会改任何东西你可以放心跑。输出会列出各个目标的当前大小、可清理大小、保留策略。确认没问题后再执行清理cursor-clean clean --lang zh默认是交互式的会问你确认。如果你想非交互一键清cursor-clean clean -y --lang zh常用参数我整理成一张表方便你按需组合参数作用示例--keep-days N只保留最近 N 天聊天cursor-clean clean --lang zh --keep-days 60-y非交互直接确认cursor-clean clean -y --lang zhclean-agents只删旧 agent 版本cursor-clean clean-agents -y --lang zhvacuum只压缩数据库cursor-clean vacuum --lang zh如果你只想处理某一类可以分开跑。比如先只删旧 agent 版本cursor-clean clean-agents -y --lang zh再单独压缩数据库cursor-clean vacuum --lang zhvacuum这个操作值得单独说。SQLite 删数据后文件不会自动变小需要执行 VACUUM 重建数据库文件才能真正释放空间。cursor-clean帮你做了这件事这也是为什么清理后能看到明显体积下降。3. 可复制的 cursor-clean 配置与清理参数这一节给你一份可以直接抄的配置和命令组合。虽然cursor-clean是命令行工具不需要写 JSON 或 TOML 配置文件但你可以把常用参数固化成一个批处理脚本省得每次敲。先看最常用的清理流程我把它写成一个.bat文件放在桌面双击就能跑echo off chcp 65001 nul echo 正在扫描 Cursor 缓存... cursor-clean scan --lang zh echo. echo 按任意键开始清理保留最近 90 天... pause nul cursor-clean clean -y --lang zh --keep-days 90 echo. echo 清理完成按任意键退出。 pause nulchcp 65001是为了让中文正常显示不然 cmd 里可能乱码。这个脚本的逻辑就是先扫描给你看暂停等你确认再执行清理。如果你想把保留天数改成 60 天把--keep-days 90改成--keep-days 60就行。想更激进一点只留 30 天就写 30。我的建议是别低于 30 天因为有些项目的上下文你可能过几周还要翻。对于想接入自动化流程的场景比如你写了个定时任务每周清理一次可以用非交互模式echo off chcp 65001 nul cursor-clean clean -y --lang zh --keep-days 90 cursor-clean clean-agents -y --lang zh cursor-clean vacuum --lang zh这三条命令分别做三件事清理 90 天前的聊天记录、删除旧 agent 版本、压缩数据库。组合起来就是一次完整清理。如果你用的是 PowerShell语法基本一样只是暂停命令不同cursor-clean scan --lang zh cursor-clean clean -y --lang zh --keep-days 90 cursor-clean vacuum --lang zh这里要提醒一个容易踩的坑批处理脚本里不要加cursor-clean的完整路径除非你确定 PATH 里有。如果你是用pip install --user装的脚本可能不在系统 PATH 里需要写成完整路径比如%APPDATA%\Python\Python311\Scripts\cursor-clean.exe clean -y --lang zh具体路径取决于你的 Python 版本和安装方式。不确定的话在 cmd 里跑where cursor-clean就能看到实际位置。关于模型和 API 的配置这里要说明一下cursor-clean本身是纯本地工具不涉及任何模型调用所以不需要配 Base URL、Key 或 Model ID。它只操作本地文件。如果你在 Cursor 里配置了自定义模型接入那是另一回事和清理工具无关。但如果你确实需要在 Cursor 里接入第三方模型服务来降低使用成本可以了解下 TaoToken 这类聚合服务。它的 API 地址是https://taotoken.net/api在 Cursor 的模型设置里填 Base URL 和对应的 Key 就能用。不过这是可选项和本文的清理主题分开你按需决定。回到清理本身。我建议你把扫描和清理分成两步不要一上来就-y。先scan看清楚哪些文件大、清理策略是什么确认没有误伤再清。这个习惯能帮你避免「手滑删了还要用的历史」这种尴尬。4. 验证清理效果与磁盘占用对比方法清理跑完之后怎么确认真的释放了空间不能只看工具的输出要自己动手验证。这里给你几种方法从简单到严谨。最直接的是看工具自己的输出。cursor-clean clean执行完会打印清理前后的对比类似这样清理前 state.vscdb: 11.2 GB 清理后 state.vscdb: 1.8 GB 释放空间: 9.4 GB但这个数字是工具算的你最好再独立验证一次。打开文件资源管理器跳到%APPDATA%\Cursor右键属性看文件夹大小。清理前记一下清理后再看一次差值就是实际释放量。更精确的方法是用命令行统计。在 PowerShell 里跑$path $env:APPDATA\Cursor $size (Get-ChildItem $path -Recurse -Force | Measure-Object -Property Length -Sum).Sum {0:N2} GB -f ($size / 1GB)这条命令会递归统计整个 Cursor 目录的大小输出以 GB 为单位。清理前后各跑一次对比结果。如果你想看具体是哪个文件变小了可以针对state.vscdb单独查Get-Item $env:APPDATA\Cursor\User\globalStorage\state.vscdb | Select-Object Name, {NSizeGB;E{{0:N2} -f ($_.Length/1GB)}}注意state.vscdb的实际路径可能是User\globalStorage\state.vscdb不同 Cursor 版本略有差异你可以用Get-ChildItem -Recurse -Filter state.vscdb先找到它。还有一个更直观的办法用 WizTree 或 TreeSize Free 这类磁盘分析工具清理前后各扫一次%APPDATA%\Cursor看树状图的变化。WizTree 读 MFT 很快几秒钟就能扫完整个盘。我实测的一组数据供你参考一台用了 8 个月的机器清理前%APPDATA%\Cursor是 19.6GB其中state.vscdb11.3GB、state.vscdb.backup4.1GB、cursor-agent2.2GB。执行cursor-clean clean -y --lang zh --keep-days 90加vacuum之后目录降到 6.8GB释放约 12.8GB。state.vscdb从 11.3GB 压到 1.9GBcursor-agent从 2.2GB 降到 0.4GB。备份文件因为默认保留还是 4.1GB如果你手动删掉能再省 4GB。验证的时候有个细节要注意vacuum执行期间会临时占用额外磁盘空间因为 SQLite 要重建文件。如果你的 C 盘已经红到只剩几百 MB可能 vacuum 会失败。这种情况先手动删掉state.vscdb.backup腾点空间再跑 vacuum。另外清理后第一次打开 Cursor 可能会稍微慢一点因为它在重建索引和加载状态。这是正常的用几次就恢复了。如果打开后发现聊天历史少了那是预期行为——超过保留天数的记录被清了。5. cursor-clean 常见报错排查与修复即使工具很简单实际跑的时候还是可能遇到问题。这一节我把常见的报错和排查方法列出来你对照着看。报错一cursor-clean不是内部或外部命令这是最常见的说明脚本不在 PATH 里。先确认装没装pip show cursor-clean如果显示已安装找到 Scripts 目录python -c import sysconfig; print(sysconfig.get_path(scripts))把打印出来的路径加到系统环境变量 PATH 里或者直接用完整路径调用。如果你用的是pip install --user路径通常在%APPDATA%\Python\PythonXX\Scripts。报错二database is locked或压缩卡住这个几乎都是因为 Cursor 没完全退出。去任务管理器确认没有Cursor.exe还要检查有没有cursor-agent.exe之类的后台进程。全部结束后再跑。如果还是锁重启一次电脑最稳妥。报错三PermissionError: [WinError 5] 拒绝访问两种可能一是文件被占用同上二是权限不够。试试用管理员身份打开 cmd 或 PowerShell 再跑。如果还不行检查%APPDATA%\Cursor的权限确保当前用户有完全控制权。报错四sqlite3.DatabaseError: file is not a database说明state.vscdb损坏了。这时候别慌先备份整个%APPDATA%\Cursor目录然后用state.vscdb.backup覆盖state.vscdb再重新跑清理。如果备份也坏了那就只能删掉state.vscdb让 Cursor 重建代价是丢失所有本地历史。报错五ModuleNotFoundError: No module named cursor_clean装是装了但导入失败通常是 Python 环境混乱。确认你用的 pip 和 python 是同一个环境python -m pip install -U cursor-clean python -m cursor_clean --version用python -m的方式调用能避免 PATH 和环境错位的问题。报错六清理后 Cursor 打不开或配置丢失这种情况一般是误删了不该删的。cursor-clean默认只动历史记录和旧 agent 版本不会碰你的设置和扩展。如果你手动删了别的文件导致问题从备份恢复。所以再强调一次清理前备份%APPDATA%\Cursor或者至少备份state.vscdb。报错七vacuum后空间没释放SQLite 的 VACUUM 需要临时空间如果磁盘满了会失败但可能不报错。先确认磁盘有足够空间再跑一次。另外如果state.vscdb里有大量未提交的事务也可能影响。重启 Cursor 再退出然后重试。排查的时候有个通用思路先看报错信息里的关键词是权限问题、占用问题还是数据库问题然后对症下药。大部分问题都能通过「完全退出 Cursor 管理员权限 备份后重试」解决。如果你在 Cursor 里配置了自定义模型接入遇到的是 API 相关的报错比如 401、连接失败那和cursor-clean无关需要检查你的 Base URL 和 Key 配置。TaoToken 的接入文档在https://taotoken.net/doc里面有各客户端的配置示例可以对照排查。6. 长期维护 Cursor 磁盘占用的实用建议清理一次能管几个月但 Cursor 会继续写历史空间还会慢慢涨回来。与其等 C 盘爆了再救火不如养成几个习惯把占用控制在合理范围。第一个习惯是定期跑cursor-clean scan。不用天天跑一个月一次就行。扫描是只读的几秒钟出结果看到体积涨到你觉得不舒服了就清一次。我一般设个日历提醒每月 1 号扫一下。第二个习惯是控制保留天数。默认 90 天对大多数人够用但如果你聊天记录特别多可以降到 60 天甚至 45 天。改法就是--keep-days 60。别设太低不然想翻旧账的时候找不到。第三个习惯是定期清cursor-agent旧版本。这个用cursor-clean clean-agents -y --lang zh单独跑很快。Agent CLI 更新频繁旧版本堆着纯占地方。第四个习惯是备份文件别长期留。state.vscdb.backup动辄几个 GB如果你确认当前数据库没问题可以手动删掉它。下次 Cursor 会重新生成。不过删之前确保 Cursor 是关的。第五个习惯是把 Cursor 的缓存目录考虑迁移。如果你 C 盘实在小可以用符号链接把%APPDATA%\Cursor指到 D 盘。方法是先退出 Cursor把整个目录移到 D 盘然后管理员权限跑mklink /D %APPDATA%\Cursor D:\CursorData这样 Cursor 还是按原路径读写实际文件在 D 盘。不过这个操作有风险迁移前务必备份而且某些 Cursor 版本可能不认符号链接试之前想清楚。第六个习惯是关注 Cursor 版本更新。官方偶尔会优化存储策略新版本可能自带清理选项。保持更新说不定哪天就不用第三方工具了。最后说下工具本身的维护。cursor-clean是开源的PyPI 页面在https://pypi.org/project/cursor-clean/仓库在https://github.com/TIZZYONE/cursor-clean.git。如果你发现 bug 或者想加功能可以提 issue 或 PR。逻辑简单改起来不难。如果你在清理之外还想优化 Cursor 的模型使用成本可以了解下 TaoToken 的 Coding Plan地址是https://taotoken.net/coding-plan适合长期编码和 Agent 场景。API Keys 管理在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc。这些是可选项按你的实际需求决定。回到磁盘这件事Cursor 很强但本地状态会悄悄长大。养成定期 scan、按需 clean 的习惯C 盘就不会再莫名其妙飘红。腾出来的往往不是几百 MB而是好几 GB。