Node.js / 系统课时

开发文件整理工具

开发文件整理工具

这一课把命令行参数和文件系统操作合成一个可执行工具:读取指定目录中的文件,按扩展名分到 images、documents、code 和 other,支持 --dry-run 预览,并在重名时自动生成新文件名。示例面向 Node.js 22 及以上。

学习目标

  • 把命令行输入转换为源目录、目标目录和预览开关。
  • 使用 readdir()、mkdir() 和文件移动操作完成分类整理。
  • 处理重名、跨文件系统移动和错误退出,并用可重复样例验收结果。

先确定最小可用规则

第一版工具只处理源目录第一层的普通文件,不递归进入子目录。分类规则保持可检查:图片识别 .jpg、.jpeg、.png、.gif、.webp;文档识别 .pdf、.txt、.md、.docx;代码识别 .js、.mjs、.cjs、.json,其余都进入 other。

--target 未提供时,目标目录使用 <source>/organized;--dry-run 为真时只打印计划,不创建目录也不移动文件。目标文件已存在时,photo.jpg 依次尝试 photo (1).jpg、photo (2).jpg,避免直接覆盖。

文件整理工具从参数到移动文件的处理流程

实现一个可直接运行的整理器

新建 organizer.mjs。代码先用 parseArgs() 解析位置参数和选项,再读取目录项;withFileTypes: true 可以直接用 entry.isFile() 跳过子目录。文件按顺序逐个处理,便于保证日志与实际操作一致。

js
import {
  access,
  copyFile,
  mkdir,
  readdir,
  rename,
  unlink,
} from 'node:fs/promises';
import { basename, extname, join, resolve } from 'node:path';
import { parseArgs } from 'node:util';

const GROUPS = {
  images: new Set(['.jpg', '.jpeg', '.png', '.gif', '.webp']),
  documents: new Set(['.pdf', '.txt', '.md', '.docx']),
  code: new Set(['.js', '.mjs', '.cjs', '.json']),
};

function categoryOf(filename) {
  const ext = extname(filename).toLowerCase();

  for (const [category, extensions] of Object.entries(GROUPS)) {
    if (extensions.has(ext)) return category;
  }

  return 'other';
}

async function uniquePath(directory, filename) {
  const ext = extname(filename);
  const stem = basename(filename, ext);
  let index = 0;

  while (true) {
    const suffix = index === 0 ? '' : ` (${index})`;
    const candidate = join(directory, `${stem}${suffix}${ext}`);

    try {
      await access(candidate);
      index += 1;
    } catch (error) {
      if (error.code === 'ENOENT') return candidate;
      throw error;
    }
  }
}

async function moveFile(from, to) {
  try {
    await rename(from, to);
  } catch (error) {
    // 跨磁盘或挂载点时 rename 可能返回 EXDEV,此时复制成功后再删除源文件。
    if (error.code !== 'EXDEV') throw error;
    await copyFile(from, to);
    await unlink(from);
  }
}

async function main() {
  const { values, positionals } = parseArgs({
    options: {
      target: { type: 'string', short: 't' },
      'dry-run': { type: 'boolean' },
    },
    allowPositionals: true,
  });

  const [sourceArg] = positionals;
  if (!sourceArg) {
    throw new Error('用法: node organizer.mjs <source> [-t <target>] [--dry-run]');
  }

  const sourceDir = resolve(sourceArg);
  const targetDir = resolve(values.target ?? join(sourceDir, 'organized'));
  const dryRun = values['dry-run'] ?? false;
  const entries = await readdir(sourceDir, { withFileTypes: true });

  entries.sort((a, b) => a.name.localeCompare(b.name));

  for (const entry of entries) {
    if (!entry.isFile()) continue;

    const category = categoryOf(entry.name);
    const categoryDir = join(targetDir, category);
    const destination = await uniquePath(categoryDir, entry.name);
    const relativeTarget = join(category, basename(destination));
    const action = dryRun ? 'DRY' : 'MOVE';

    console.log(`${action} ${entry.name} -> ${relativeTarget}`);

    if (!dryRun) {
      await mkdir(categoryDir, { recursive: true });
      await moveFile(join(sourceDir, entry.name), destination);
    }
  }
}

main().catch((error) => {
  console.error(`ERROR: ${error.message}`);
  process.exitCode = 1;
});

这份实现不会覆盖已有同名文件。mkdir(..., { recursive: true }) 允许分类目录已存在;rename() 在同一文件系统内直接移动,若目标位于另一个磁盘或挂载点而出现 EXDEV,则退回 copyFile() 加 unlink()。

用固定样例验证 dry-run 和真实移动

先在空的 demo-inbox 中创建四个测试文件,再连续执行预览和正式整理。下面的第一条命令只创建测试数据,不打印内容;后两条命令应先显示 DRY,再显示 MOVE。

bash
node -e "const fs=require('node:fs'); fs.mkdirSync('demo-inbox',{recursive:true}); for (const f of ['app.js','archive.zip','notes.txt','photo.jpg']) fs.writeFileSync('demo-inbox/'+f,'demo');"
node organizer.mjs ./demo-inbox --dry-run
node organizer.mjs ./demo-inbox

预期输出:

text
DRY app.js -> code/app.js
DRY archive.zip -> other/archive.zip
DRY notes.txt -> documents/notes.txt
DRY photo.jpg -> images/photo.jpg
MOVE app.js -> code/app.js
MOVE archive.zip -> other/archive.zip
MOVE notes.txt -> documents/notes.txt
MOVE photo.jpg -> images/photo.jpg

正式执行后,demo-inbox 顶层不再有这四个测试文件,目标会位于 demo-inbox/organized 的四个分类目录中。再次创建一个 photo.jpg 后运行整理器,如果 organized/images/photo.jpg 已存在,新文件应进入 photo (1).jpg。

明确第一版工具的边界

这个版本故意跳过子目录,因此 readdir() 得到目录项后只处理 entry.isFile() 为真的项目;需要递归整理时,应单独增加递归遍历,而不是把已有目录直接移动进分类目录。对正在下载或被其他程序持续写入的文件,也不建议边写边整理。

重名检测采用“检查后再移动”的顺序,适合单进程本地工具;如果多个进程同时整理同一个目录,仍可能在检查与写入之间发生竞争。上线到并发环境前,应改成带原子占位或集中任务队列的方案,而不是仅依赖 access() 判断文件名是否可用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

开发文件整理工具

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通