Loading... # Claude 垃圾文件清理脚本技术文档 # 一、概述 ## 1. 简介 ### A. 是什么 cleanup.sh 是一个专为 Claude Code CLI 设计的自动化垃圾文件清理脚本，用于清理运行过程中产生的各类临时文件、历史记录和缓存数据，释放磁盘空间。 ### B. 为什么需要 Claude Code 在日常使用中会产生大量临时文件，包括调试日志、会话环境、任务列表、备份文件等。这些文件随着时间积累会占用大量磁盘空间，但其中大部分历史文件已无实际保留价值。定期清理这些文件可以： - 释放磁盘空间 - 提升文件系统性能 - 保持工作目录整洁 ### C. 功能特点 - 按保留数量策略清理各目录 - 支持预览模式，可预先查看删除内容 - 完整的统计报告（释放空间、删除文件数） - 集成日志记录功能 - 安全的文件删除机制 ## 2. 前置知识 ### A. 必备技能 - 基本 Linux 命令行操作 - Bash 脚本基础理解 ### B. 推荐知识 - 了解 Claude Code 目录结构 - 熟悉 cron 定时任务配置 # 二、脚本架构 ## 1. 目录结构 ```mermaid graph TB A[Claude Home] --> B[scripts/] A --> C[lib/] A --> D[logs/] A --> E[各清理目标目录] B --> B1[cleanup.sh] C --> C1[logger.sh] C --> C2[rsync-config.sh] D --> D1[operations_YYYYMMDD.log] E --> E1[debug/] E --> E2[file-history/] E --> E3[todos/] E --> E4[backups/] ```  ## 2. 工作原理 ```mermaid flowchart TD A[启动脚本] --> B{检查运行模式} B -->|预览模式| C[计算待删除文件] B -->|执行模式| D[执行清理操作] C --> E[生成预览报告] D --> F[记录操作日志] E --> G[输出统计报告] F --> G G --> H[结束] ```  ## 3. 清理策略 脚本采用基于保留数量的清理策略，各目录保留规则如下： | 目录 | 保留策略 | 保留数量 | 清理依据 | |------|---------|---------|---------| | debug/ | 按文件数量 | 3 个 | 修改时间倒序 | | file-history/ | 按会话数量 | 50 个 | 修改时间倒序 | | session-env/ | 按会话数量 | 20 个 | 修改时间倒序 | | todos/ | 按文件数量 | 200 个 | 修改时间倒序 | | shell-snapshots/ | 按文件数量 | 10 个 | 修改时间倒序 | | plans/ | 按文件数量 | 20 个 | 修改时间倒序 | | transcripts/ | 按文件数量 | 10 个 | 修改时间倒序 | | backups/ | 按文件数量 | 1 个 | 修改时间倒序 | | paste-cache/ | 全部清理 | 0 个 | 无条件删除 | | 根目录杂项 | 按天数 | 30 天 | 文件修改时间 | # 三、核心实现 ## 1. 配置管理 脚本使用关联数组（Associative Array）管理配置参数： ```bash declare -A CONFIG=( [debug_keep]=3 [history_keep]=50 [session_keep]=20 [todos_keep]=200 [snapshots_keep]=10 [plans_keep]=20 [transcripts_keep]=10 [backups_keep]=1 [old_file_days]=30 ) ``` 配置项命名规范：`<目录前缀>_keep` 表示保留数量，`old_file_days` 表示天数阈值。 ## 2. 空间计算 calculate_space 函数使用系统命令获取文件或目录大小： ```mermaid sequenceDiagram participant C as calculate_space participant D as du/stat 命令 participant A as awk C->>D: 检查路径类型 alt 目录 D->>C: 返回 du -sk 结果 else 文件 D->>C: 返回 stat -c%s 结果 end C->>A: 提取数值并转换为字节 A->>C: 返回字节数 ```  核心实现： ```bash calculate_space() { local path="$1" if [ -d "$path" ]; then du -sk "$path" 2>/dev/null | awk '{print $1 * 1024}' elif [ -f "$path" ]; then stat -c%s "$path" 2>/dev/null || echo 0 else echo 0 fi } ``` ## 3. 按数量清理 clean_by_count 函数实现基于保留数量的文件清理： ```mermaid flowchart TD A[开始] --> B[目录是否存在?] B -->|否| C[返回] B -->|是| D[计算清理前空间] D --> E[使用 find 统计文件数] E --> F[计算需删除数量] F --> G{需删除?} G -->|否| C G -->|是| H{预览模式?} H -->|是| I[列出待删除文件] H -->|否| J[按时间排序后删除] I --> K[计算清理后空间] J --> L[记录日志] L --> K K --> M[更新统计并输出] ```  关键技术点： 1. 使用 find 命令按修改时间排序： ```bash find "$target_dir" -maxdepth 1 -type f -printf '%T@ %p\n' 2>/dev/null | \ sort -rn | \ tail -n +$((keep_count + 1)) | \ cut -d' ' -f2- ``` 2. 防止 set -e 导致脚本退出： ```bash TOTAL_DELETED=$((TOTAL_DELETED + delete_count)) || true TOTAL_FREED=$((TOTAL_FREED + freed)) || true CLEANED_DIRS=$((CLEANED_DIRS + 1)) || true ``` ## 4. 特殊清理函数 clean_paste_cache：清空粘贴缓存目录（全部删除） clean_root_misc：清理根目录杂项文件（按天数） # 四、使用方法 ## 1. 基本用法 查看帮助信息： ```bash /home/lab/.claude/scripts/cleanup.sh --help ``` 预览模式（不实际删除）： ```bash /home/lab/.claude/scripts/cleanup.sh --dry-run ``` 执行清理： ```bash /home/lab/.claude/scripts/cleanup.sh ``` 自动确认并详细输出： ```bash /home/lab/.claude/scripts/cleanup.sh -y -v ``` ## 2. 命令行选项 | 选项 | 长选项 | 说明 | |------|--------|------| | -d | --dry-run | 预览模式，不实际删除文件 | | -y | --yes | 自动确认，不询问 | | -v | --verbose | 详细输出，启用 DEBUG 日志级别 | | -h | --help | 显示帮助信息 | ## 3. 输出示例 预览模式输出： ``` ======================================== Claude 垃圾文件清理工具 ======================================== 工作目录: /home/lab/.claude 模式: 预览 (DRY-RUN) ======================================== [DRY-RUN] debug: 将删除 8 个文件 - 7d380f20-16eb-48da-ada5-063d12dc7c78.txt - c436eebe-58e5-4fa1-ab3d-f9a484b97330.txt ... debug: 1MB → 1MB [释放: 0B] ======================================== 清理完成报告 ======================================== 释放空间: 0B 删除文件数: 2540 清理目录数: 9 ======================================== ``` 执行模式输出： ``` ======================================== Claude 垃圾文件清理工具 ======================================== 工作目录: /home/lab/.claude 模式: 执行 ======================================== debug: 1.2M → 584K [释放: 600K] todos: 8.1M → 1.1M [释放: 7MB] ... ======================================== 清理完成报告 ======================================== 释放空间: 21MB 删除文件数: 2540 清理目录数: 9 ======================================== ``` # 五、依赖库 ## 1. logger.sh 日志库提供统一的日志功能： ```mermaid classDiagram class logger_sh { +LOG_DIR: string +LOG_FILE: string +LOG_LEVEL: string +LOG_LEVELS: map +log(level, message) +cleanup_logs() +rotate_log() } ```  核心功能： - 日志级别控制（DEBUG/INFO/WARN/ERROR） - 日志文件按日期分割 - 日志自动轮转（单文件超过 10MB） - 带颜色的控制台输出 ## 2. rsync-config.sh 配置库提供共享配置： ```mermaid classDiagram class rsync_config_sh { +RED: string +GREEN: string +BLUE: string +NC: string +EXCLUDE_ARGS: array +RSYNC_OPTIONS: string +get_script_dir() +test_ssh_connection() +do_rsync() } ```  # 六、定时任务配置 ## 1. cron 配置 编辑 crontab： ```bash crontab -e ``` 添加定时任务： ```bash # 每周日凌晨 2 点执行清理 0 2 * * 0 /home/lab/.claude/scripts/cleanup.sh --yes # 每天凌晨 3 点执行清理 0 3 * * * /home/lab/.claude/scripts/cleanup.sh --yes # 每月 1 号凌晨 2 点执行清理 0 2 1 * * /home/lab/.claude/scripts/cleanup.sh --yes ``` ## 2. 日志轮转 日志文件会自动清理 30 天前的记录： ```bash cleanup_logs() { find "$LOG_DIR" -name "operations_*.log" -mtime +$LOG_MAX_DAYS -delete } ``` # 七、故障排查 ## 1. 常见问题 | 问题 | 原因 | 解决方法 | |------|------|---------| | 脚本无法执行 | 缺少执行权限 | 运行 chmod +x cleanup.sh | | 清理后空间未释放 | 其他进程占用文件 | 重启相关服务或系统 | | 日志未记录 | LOG_DIR 不存在 | 脚本会自动创建目录 | | find 命令报错 | 系统不支持 -printf | 使用 GNU findutils | ## 2. 调试方法 启用详细输出： ```bash /home/lab/.claude/scripts/cleanup.sh -v --dry-run ``` 查看日志文件： ```bash cat /home/lab/.claude/logs/operations_$(date +%Y%m%d).log ``` 手动测试清理函数： ```bash # 只清理 debug 目录，保留 3 个文件 find /home/lab/.claude/debug -maxdepth 1 -type f -printf '%T@ %p\n' | \ sort -rn | tail -n +4 | cut -d' ' -f2- ``` # 八、扩展与定制 ## 1. 修改保留数量 编辑脚本中的 CONFIG 关联数组： ```bash declare -A CONFIG=( [debug_keep]=5 # 修改为保留 5 个 [todos_keep]=500 # 修改为保留 500 个 ... ) ``` ## 2. 添加新的清理目录 在 main 函数中添加： ```bash clean_by_count "new-directory" 100 # 保留 100 个文件 ``` ## 3. 自定义清理规则 创建自定义清理函数： ```bash clean_custom() { local target_dir="${CLAUDE_HOME}/custom-dir" if [ ! -d "$target_dir" ]; then return 0 fi # 自定义清理逻辑 find "$target_dir" -name "*.tmp" -mtime +7 -delete log INFO "已清理 custom-dir 中的临时文件" } ``` # 九、最佳实践 ## 1. 使用建议 - 首次使用前先运行 --dry-run 预览 - 定期（每周或每月）执行清理 - 重要数据备份后再执行清理 - 根据实际使用情况调整保留数量 ## 2. 安全注意事项 - 脚本不会删除 settings.json 和 .credentials.json - skills/、plugins/、lib/ 等核心目录不会被清理 - 建议在配置文件中明确排除重要目录 ## 3. 性能优化 - 使用 find -printf 而非 ls -t，性能更优 - 使用管道并行处理，提高清理速度 - 大量文件清理时建议分批进行 *** ## 参考资料 1. [Bash Guide for Beginners](https://tldp.org/LDP/Bash-Beginners-Guide/html/) 2. [GNU Findutils Manual](https://www.gnu.org/software/findutils/manual/) 最后修改：2026 年 02 月 05 日 © 允许规范转载 赞 如果觉得我的文章对你有用，请随意赞赏