file-cleanup-cli

一个基于 Node.js 的命令行文件清理工具，具有回收站功能，可按扩展名、保留天数批量移动指定文件夹及其子目录中的旧文件到自定义回收站目录，或根据需要直接删除符合条件的文件，提供配置管理、系统保护与详细日志记录。

技术架构

项目结构

file-cleanup-cli/
├── bin/             # CLI 命令行入口
│   └── cli.js       # 命令行执行脚本
├── app.js           # 主应用入口
├── cleaner.js       # 核心清理逻辑
├── configManager.js # 配置管理模块
├── logger.js        # 日志管理模块
├── config.yaml      # 配置文件
├── package.json     # 项目配置和依赖
└── README.md        # 项目文档

核心模块职责

app.js - 主应用入口，负责命令行参数解析、操作分发和用户交互
cleaner.js - 核心清理逻辑，实现文件检查、移动和删除功能
configManager.js - 配置管理，处理文件夹的添加、删除、更新和查询
logger.js - 日志管理，记录操作过程和错误信息
bin/cli.js - CLI 命令行入口，全局安装后可通过 file-cleanup 命令调用

技术栈

运行环境：Node.js >= 22.19.0
核心依赖：
- fs-extra：增强的文件系统操作
- js-yaml：YAML 配置文件解析
- winston：日志管理
开发规范：ES6 语法，中文注释，模块化设计

功能特性

📁 多文件夹管理 - 支持配置多个文件夹进行清理
⏰ 灵活的保留策略 - 自定义文件保留天数
🔒 文件格式限制 - 只处理指定格式的文件
🛡️ 系统保护 - 自动保护系统文件和重要文件，禁止在关键系统路径上执行操作
📊 详细日志 - 完整的操作日志记录，使用 winston 进行日志管理
🔄 递归清理 - 自动清理子文件夹中的符合条件文件
🔍 文件使用检查 - 避免处理正在使用的文件
📝 相对路径支持 - 支持使用相对路径配置清理文件夹，自动转换为绝对路径存储
🗑️ 直接删除功能 - 可直接删除符合条件的文件，不执行移动操作
♻️ 回收站功能 - 自动将清理的文件移动到自定义回收站目录，移动时保留原始文件结构，使用三重验证确保数据完整性
⚙️ 回收站自定义设置 - 可配置回收站目录路径

安装

环境要求

Node.js: >= 22.19.0
npm: >= 10.0.0 (通常随 Node.js 一起安装)
操作系统: Windows 10 或以上版本

前置依赖

在安装本工具前，请确保您的系统已经安装了以下软件：

Node.js - 您可以从 Node.js 官网下载并安装最新版本
npm - 通常随 Node.js 一起安装，也可以通过 npm install -g npm@latest 更新到最新版本

验证前置依赖

在开始安装前，建议先验证 Node.js 和 npm 是否正确安装：

# 检查 Node.js 版本
node -v

# 检查 npm 版本
npm -v

如果命令执行成功并显示版本号，说明前置依赖已经准备就绪。

安装方式

本地安装

本地安装仅在当前项目目录下可用，通常用于项目集成或开发场景：

# 克隆仓库
git clone https://github.com/whmyxh/file-cleanup-cli.git

# 进入您的项目目录
cd /path/to/your/project

# 安装到本地项目
npm install .

验证安装成功

安装完成后，可以通过以下方式验证安装是否成功：

验证全局安装

# 检查工具版本
file-cleanup --version

# 查看帮助信息
file-cleanup --help

如果命令执行成功并显示版本信息或帮助文档，说明全局安装成功。

卸载工具

如果您需要卸载本工具，可以使用以下命令：

# 卸载全局安装的工具
npm uninstall -g file-cleanup-cli

使用方法

基本命令

file-cleanup [选项]

命令选项

清理操作选项

-d, --days <天数> - 指定文件保留天数（默认: 0天），必须与--clear参数搭配使用才能生效
--clear, -c - 执行文件清理操作
-f, --force - 强制删除文件（跳过回收站），但会触发确认提示
- 与--clear搭配使用时，将直接删除符合条件的文件，不执行移动到回收站的操作
- 注意: 直接删除的文件不可恢复，请谨慎使用
-y - 自动跳过所有需要用户交互确认的操作，直接执行默认选项
- 与--clear搭配使用时，将按默认方式执行清理操作（移动到回收站）
- 与-f搭配使用时，将跳过-f参数的确认提示，直接执行强制删除
- 与--configclear搭配使用时，将自动确认并清空配置

配置管理选项

--add, -a <路径> - 添加文件夹到配置（支持绝对路径和相对路径）
--remove, -rm <路径> - 从配置中删除文件夹（支持绝对路径和相对路径）
--update, -u <旧路径> <新路径> - 修改配置中的文件夹路径（支持绝对路径和相对路径）
--list, -l - 列出所有配置的文件夹
--configclear, -cfc - 清空所有文件夹配置（保留其他配置项）
--recycle-bin, -rb <路径> - 设置回收站目录（支持绝对路径和相对路径）
--list-recycle-bin, -lrb - 列出当前回收站目录设置

其他选项

-h, --help - 显示帮助信息
-v, --version - 显示版本信息

参数组合规则

核心规则

-d, --days 参数 - 必须与 --clear 参数搭配使用才能生效
- 单独使用 -d 或 --days 参数时，系统将忽略该参数设置
- 该参数仅在执行清理操作时有效，用于临时覆盖默认保留天数
-f, --force 参数 - 可以与需要确认的操作参数搭配使用
- 与 --clear 搭配：强制删除符合条件的文件，不执行移动操作，并触发确认提示
  - 此模式下文件不会被移动到回收站，而是直接从磁盘删除
  - 直接删除的文件不可恢复，请谨慎使用
- 使用此参数时请格外谨慎，因为它会直接删除文件，且文件不可恢复
-y 参数 - 自动跳过所有需要用户交互确认的操作
- 与 --clear 搭配：按默认方式执行清理操作（移动到回收站），跳过确认提示
- 与 -f 搭配：跳过 -f 参数的确认提示，直接执行强制删除
- 与 --configclear 搭配：自动确认并清空配置

使用场景

默认保留天数清理（回收站模式） - 当您想使用配置文件中的默认保留天数（0天）进行清理，并将文件移动到回收站时
```
file-cleanup --clear
```
自定义保留天数清理（回收站模式） - 当您需要临时使用特定的保留天数进行清理，并将文件移动到回收站时
```
file-cleanup --clear --days 30
```
直接删除文件（跳过回收站） - 当您需要直接删除符合条件的文件，不执行移动操作时
```
file-cleanup --clear --force
```
自定义天数直接删除（跳过回收站） - 当您需要直接删除超过特定天数的文件，不执行移动操作时
```
file-cleanup --clear --days 30 --force
```
配置管理 - 当您仅需管理清理配置（添加、删除、修改文件夹）时
```
file-cleanup --add ./logs
file-cleanup --remove ./logs
file-cleanup --list
```
自动确认清理（回收站模式） - 当您需要执行清理操作并自动跳过确认提示时
```
file-cleanup --clear -y
```
自动确认清空配置 - 当您需要清空所有文件夹配置且自动跳过确认提示时
```
file-cleanup --configclear -y
```

无效参数组合示例

以下参数组合将不会产生预期效果，系统会忽略多余的参数：

file-cleanup --days 30 - 仅指定天数，未执行清理操作
file-cleanup --add ./logs --days 30 - 配置操作中使用天数参数
file-cleanup --list --days 30 - 列表操作中使用天数参数

使用示例

配置管理（添加、删除、修改文件夹）

添加文件夹到配置

# 使用绝对路径
file-cleanup --add "E:\temp\logs"

# 使用相对路径
file-cleanup --add ./logs
file-cleanup --add ../temp/files

从配置中删除文件夹

# 使用绝对路径
file-cleanup --remove "E:\temp\logs"

# 使用相对路径
file-cleanup --remove ./logs

修改配置中的文件夹路径

# 使用绝对路径
file-cleanup --update "E:\temp\logs" "E:\temp\new_logs"

# 使用相对路径
file-cleanup --update ./old-folder ./new-folder

列出所有配置的文件夹

file-cleanup --list

清空所有文件夹配置

file-cleanup --configclear

回收站目录管理

设置回收站目录

# 使用绝对路径
file-cleanup --recycle-bin "E:\recycle-bin"

# 使用相对路径
file-cleanup --recycle-bin ./recycle-bin

列出当前回收站目录设置

file-cleanup --list-recycle-bin

执行清理

使用默认保留天数（0天，回收站模式）

file-cleanup --clear

指定保留天数（回收站模式）

file-cleanup --clear --days 30

直接删除文件（跳过回收站）

file-cleanup --clear --force

指定保留天数直接删除（跳过回收站）

file-cleanup --clear --days 30 --force

自动确认清理（回收站模式）

file-cleanup --clear -y

自动确认清理并指定保留天数（回收站模式）

file-cleanup --clear --days 30 -y

自动确认清空配置

file-cleanup --configclear -y

配置文件

config.yaml

配置文件位于安装目录下，包含以下配置项：

# 清理脚本配置文件
# 定义清理规则和保留策略

# 默认文件保留天数（单位：天）
retentionDays: 0

# 允许删除的文件扩展名列表（区分大小写）
# 支持通配符 `*` 表示所有文件类型，注意：通配符必须使用引号包裹
allowedExtensions:
  - docx
  - xlsx
  - csv
  - pptx
  - txt
  - xls

# 系统保护文件列表（文件名，不区分大小写）
protectedFiles:
  - desktop.ini
  - thumbs.db
  - $recycle.bin
  - system volume information

# 日志配置
logConfig:
  # 日志级别：error, warn, info, verbose, debug, silly
  level: info
  # 日志文件路径
  filePath: logs/cleanup.log
  # 日志文件最大大小（单位：MB）
  maxSize: 10
  # 日志文件最大数量
  maxFiles: 5

# 文件移动配置（回收站设置）
moveConfig:
  # 文件移动目标目录（支持绝对路径或相对于项目根目录的路径）
  # 此目录作为回收站使用，清理的文件将被移动到这里
  targetDirectory: "trash"

# 要清理的文件夹列表（绝对路径）
folders:

注意事项

数据安全
- 使用 --force 参数时，文件将被直接删除且不可恢复，请谨慎使用
- 建议在执行清理操作前，先备份重要文件
- 移动文件过程中会进行三重内容完整性验证（文件大小比对、内容长度验证、MD5校验和比对），确保数据安全
- 复制失败时自动清理不完整目标文件，保留原始文件，验证通过后才删除源文件
系统保护
- 工具会自动跳过系统保护文件和目录，避免误删系统文件
- 当使用通配符 * 配置时，工具会进行额外的安全检查，禁止在系统关键路径上执行操作
- 系统关键路径包括：C:\, C:\Windows, C:\System32, C:\Program Files, C:\Program Files (x86), C:\ProgramData, D:\, E:\ 等根目录和系统目录
性能考虑
- 清理大量文件时可能会消耗较多系统资源，请确保系统有足够的内存和磁盘空间
- 对于大文件的移动操作，可能需要较长时间，请耐心等待
- 移动大文件时会进行MD5校验，可能会增加处理时间，但确保数据完整性
路径处理
- 支持使用相对路径配置清理文件夹，系统会自动转换为绝对路径存储
- 路径中包含空格时，请使用引号包裹路径
- 路径验证会检查无效字符（<>:"|?*），确保路径格式正确
- 路径验证会检查文件夹是否存在、是否为文件夹、是否有读取和写入权限
日志管理
- 日志文件默认存储在 logs/cleanup.log，建议定期检查日志文件大小
- 可通过配置文件调整日志级别和存储设置
- 日志记录详细的操作过程，包括文件路径、大小、校验和等信息
错误处理
- 工具会自动跳过正在使用的文件，避免因删除正在使用的文件导致系统错误
- 操作过程中出现错误时，会记录详细的错误信息到日志文件
- 移动文件失败时会清理目标文件，确保不会留下不完整的文件
权限要求
- 需要具有目标文件夹的读取和写入权限
- 需要具有回收站目录的写入权限
- 路径验证会检查权限，确保操作能够正常执行

清理规则

文件保留策略 - 只删除超过指定天数的文件
- 同时检查文件的创建时间和修改时间，使用最新时间计算文件年龄
- 确保即使文件创建时间无效也能正确判断
文件格式限制 - 只删除配置中允许的文件格式
- 通过文件扩展名进行判断（区分大小写）
- 可以在配置文件中灵活添加或移除支持的格式
- 支持通配符 * 表示所有文件类型（注意：通配符必须使用引号包裹）
系统保护 - 自动跳过系统保护文件
- 保护系统关键文件如 desktop.ini, thumbs.db,系统根目录等
- 可在配置文件中扩展保护文件列表
文件使用检查 - 避免删除正在使用的文件
- 通过安全的读写模式验证文件是否可访问
- 防止因删除正在使用的文件导致的系统错误
- 避免使用写入模式打开文件，确保文件内容不被清空
递归清理 - 自动清理子文件夹
- 深入所有子文件夹查找符合条件的文件
- 保持文件夹结构不变
日志记录 - 完整记录所有操作
- 记录成功移动的文件
- 记录跳过的文件及其原因
- 记录错误信息以便排查问题
文件处理 - 根据操作模式处理符合条件的文件
- 常规模式（回收站模式）：将文件移动到指定的回收站目录并保留原始目录结构
  - 移动后的文件可以在回收站中查看和恢复
- 直接删除模式：当同时使用--clear和--force参数时，直接删除符合条件的文件，不执行移动操作
  - 直接删除的文件不可恢复，请谨慎使用
  - 此模式会触发确认提示，用户需要确认后才会执行删除操作
  - 如果同时使用-y参数，则会跳过确认提示，直接执行强制删除

日志文件

日志文件默认位于 logs/cleanup.log，包含以下信息：

操作时间戳
日志级别（INFO、WARN、ERROR）
操作详情
错误信息（如有）

相对路径使用说明

工具支持使用相对路径配置清理文件夹，路径解析规则如下：

当前目录相对路径：./subfolder, ./file.txt
上级目录相对路径：../parentfolder, ../../grandparentfolder
多级相对路径：./subfolder1/subfolder2, ../parentfolder/subfolder

注意：相对路径会自动转换为绝对路径存储在配置文件中

系统要求

Node.js >= 22.19.0
npm >= 10.0.0
Windows 10 或以上版本

许可证

Apache2.0 License

作者

whmyxh hmyxhxjr@qq.com

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.trae/rules		.trae/rules
bin		bin
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
app.js		app.js
cleaner.js		cleaner.js
config.yaml		config.yaml
configManager.js		configManager.js
logger.js		logger.js
package-lock.json		package-lock.json
package.json		package.json
test.js		test.js

License

whmyxh/file-cleanup-cli

Folders and files

Latest commit

History

Repository files navigation