Node Utils

Node.js 实用工具集合。

工具列表

1. 文件搬运工具 (utils/file-mover.js)

将指定源文件夹下的所有（或符合条件的）文件移动到目标文件夹。支持递归扫描、扩展名过滤、自动重命名防冲突、跨驱动器搬运。

功能

• 多源文件夹 → 单目标文件夹
• 递归/非递归扫描子目录
• 文件扩展名白名单/黑名单
• 文件大小范围过滤
• 同名文件自动重命名（文件名_1.ext）或跳过
• 跨驱动器自动切换为 copy+delete
• --dry-run 预览模式

用法

node utils/file-mover.js                # 执行搬运（使用默认配置）
node utils/file-mover.js --dry-run      # 预览模式，不实际移动
node utils/file-mover.js --config=my-config.json  # 使用自定义配置文件

配置项

配置项	说明	默认值
destDir	目标文件夹路径	D:\TEMU\样机套图\全部源文件
sourceDirs	源文件夹路径数组	—
options.recursive	是否递归子目录	true
options.extensions	文件扩展名白名单（空=全部）	[]
options.excludeExtensions	排除的文件扩展名	['.lnk', '.tmp']
options.maxFileSize	最大文件大小（字节，0=不限）	0
options.minFileSize	最小文件大小（字节）	0
options.conflictStrategy	重名策略：rename 或 skip	rename

---

2. 图片去重检测工具 (utils/image-dedup.js)

检测目标文件夹 A 中的图片是否与参考文件夹中的图片重复，以及目标文件夹内部是否存在重复，将重复文件移至 检测重复文件夹。

支持 感知哈希（pHash） 和 精确哈希（crypto） 两种模式。

功能

• 与参考文件夹比对：目标图片 vs 参考文件夹，发现重复
• 目标文件夹内部去重：目标文件夹自身图片互相比较，保留最大的，移除其余
• 感知哈希（pHash，默认）：使用 dHash 算法，能检测加滤镜、调色、调亮度/对比度后的相同图片
• 精确哈希（crypto）：使用 MD5/SHA256 精确匹配，只检测字节完全相同的文件

用法

node utils/image-dedup.js                          # 默认 phash 模式
node utils/image-dedup.js --mode=phash             # 感知哈希模式（默认）
node utils/image-dedup.js --mode=crypto            # 精确哈希模式
node utils/image-dedup.js --threshold=10           # 调整 phash 相似度阈值
node utils/image-dedup.js --hash=sha256            # crypto 模式使用 SHA256
node utils/image-dedup.js --dry-run                # 只检测不移动
node utils/image-dedup.js --config=my.json         # 使用自定义配置文件

配置项

配置项	说明	默认值
targetDir	目标文件夹 A（待检测）	D:\TEMU\样机套图\待处理\0519
referenceDirs	参考文件夹列表（用于比对）	['D:\\TEMU\\样机套图\\全部源文件']
options.mode	检测模式: phash 或 crypto	phash
options.phashThreshold	感知哈希阈值 (0-64, 越小越严格)	8
options.hashAlgorithm	哈希算法 (crypto 模式: md5/sha256)	md5
options.sizeCheck	是否先比对文件大小加速 (crypto 模式)	true
options.recursive	是否递归子目录	true
options.imageExtensions	图片扩展名列表	['.jpg','.png','.webp',...]

感知哈希（pHash）说明

使用差异哈希（dHash）算法：

1. 将图片缩放到 9×8 灰度图
2. 逐行比较相邻像素：左边 < 右边 → 位为 1，否则为 0
3. 生成 64 位 哈希值
4. 用 汉明距离（Hamming Distance）比较两张图片的哈希值，距离越小越相似

阈值参考：

阈值范围	含义
0–4	几乎相同（或轻微压缩差异）
5–10	加了滤镜、调色、调亮度
10–20	可能不同（需人工判断）
>20	不同图片

默认阈值 8 适合大部分场景。如果漏判了加滤镜的图片，可适当调高（如 --threshold=10）；如果误判太多，可调低。

---

3. 文件去重清理工具 (utils/remove-duplicates.js)

去除目标文件夹 A 中与对照文件夹列表里存在的同名文件（照片等）。

匹配原则：默认仅比对文件名（同名即视为重复），可选开启内容校验避免误判。

功能

• 目标文件夹 A vs 多个对照文件夹，按文件名去除重复
• 可选内容校验模式：none（仅文件名）、size（文件名+大小）、md5（文件名+MD5）
• 两种处理方式：move（移至隔离目录，安全）或 delete（直接删除）
• 递归/非递归子目录扫描
• 文件扩展名白名单/黑名单
• --dry-run 预览模式

用法

node utils/remove-duplicates.js                        # 执行清理（使用默认配置）
node utils/remove-duplicates.js --dry-run              # 预览模式，不实际移除
node utils/remove-duplicates.js --action=move          # 移动到隔离目录（默认，推荐）
node utils/remove-duplicates.js --action=delete        # 直接删除（谨慎）
node utils/remove-duplicates.js --content-check=size   # 文件名+大小一致才移除
node utils/remove-duplicates.js --content-check=md5    # 文件名+MD5一致才移除（最准确）
node utils/remove-duplicates.js --config=my-config.json # 使用自定义配置文件

配置项

配置项	说明	默认值
targetDir	目标文件夹 A（待清理）	空（必填）
referenceDirs	对照文件夹列表（数组，可多个）	[]（必填）
options.recursive	是否递归子目录	true
options.includeExtensions	文件扩展名白名单（空=全部）	[]
options.excludeExtensions	排除的文件扩展名	['.lnk', '.tmp']
options.action	处理方式: move 或 delete	move
options.trashDir	隔离目录路径（action=move 时有效）	目标文件夹同级/_已去除重复
options.contentCheck	内容校验: none / size / md5	none

内容校验模式说明

模式	匹配规则	速度	适用场景
none	仅文件名一致	⚡ 最快	确信同名就是同一张照片
size	文件名+文件大小一致	🚀 快	防止同名但不同尺寸的误删
md5	文件名+MD5哈希一致	🐢 较慢	需要绝对精准匹配

示例

# 仅按文件名去除（同名即重复）
node utils/remove-duplicates.js

# 预览：文件名+大小一致才算重复
node utils/remove-duplicates.js --content-check=size --dry-run

# 按文件名去重，只处理 jpg/png，直接删除
node utils/remove-duplicates.js --action=delete --config=my-config.json

配置文件示例 (my-config.json):

{
  "targetDir": "D:\\照片\\待整理",
  "referenceDirs": [
    "D:\\照片\\已归档",
    "E:\\备份\\照片"
  ],
  "options": {
    "contentCheck": "size",
    "includeExtensions": [".jpg", ".png", ".heic"],
    "action": "move"
  }
}

---

4. 图片统一尺寸工具 (utils/image-resizer.js)

将源文件夹中的图片统一处理为 2000×2000 分辨率，默认强制拉伸铺满（无白边），按文件修改时间戳排序命名输出。

功能

• fill 模式（默认）：强制拉伸到 2000×2000，铺满无白边
• cover 模式：按比例缩放 + 居中裁剪，不变形、无白边
• contain 模式：按比例缩放 + 背景填充，不变形但有白边
• 按文件修改时间戳排序，输出文件以 YYYYMMDD_HHmmss.jpg 格式命名
• 同一秒多张图片自动追加序号（_02、_03...）
• 支持递归扫描子目录
• 支持多种输出格式：JPEG / PNG / WebP / AVIF

用法

node utils/image-resizer.js                         # 默认 fill 拉伸，2000×2000，无白边
node utils/image-resizer.js --dry-run               # 预览模式
node utils/image-resizer.js --mode=cover            # 裁剪模式（不变形，无白边）
node utils/image-resizer.js --format=webp           # 输出 WebP
node utils/image-resizer.js --quality=95            # 高质量
node utils/image-resizer.js --config=my.json        # 使用自定义配置

配置项

配置项	说明	默认值
sourceDir	源文件夹	空（必填）
options.width	目标宽度	2000
options.height	目标高度	2000
options.mode	适配模式: fill / cover / contain	fill
options.background	背景色（contain 模式）	白色
options.outputFormat	输出格式: jpeg / png / webp / avif / same	jpeg
options.quality	输出质量 (1-100)	92
options.outputDir	输出文件夹	sourceDir/处理后
options.recursive	是否递归子目录	true
options.imageExtensions	图片扩展名列表	['.jpg','.png','.webp',...]

适配模式说明

模式	效果	白边	说明
fill（默认）	强制拉伸铺满 2000×2000	无	简单粗暴，全部填满
cover	按比例缩放 + 居中裁剪	无	不变形，但边缘可能被裁
contain	按比例缩放 + 背景填充	有	不变形，完整保留画面

命名规则

按文件修改时间戳排序，输出文件名为：

20250526_143022.jpg       ← 单张
20250526_143022_02.jpg    ← 同一秒有多张时
20250526_143022_03.jpg    ← ...

示例

# 默认：fill 拉伸，2000×2000，无白边
node utils/image-resizer.js

# 预览：看看会输出哪些文件
node utils/image-resizer.js --dry-run

# 裁剪模式（不变形，无白边）+ WebP 输出
node utils/image-resizer.js --mode=cover --format=webp

# 高质量 JPEG 输出
node utils/image-resizer.js --quality=98

# 自定义配置
node utils/image-resizer.js --config=my-config.json

配置文件示例 (my-config.json):

{
  "sourceDir": "D:\\照片\\待处理",
  "options": {
    "width": 2000,
    "height": 2000,
    "mode": "fill",
    "outputFormat": "jpeg",
    "quality": 95,
    "outputDir": "D:\\照片\\已处理"
  }
}