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() 跳过子目录。文件按顺序逐个处理,便于保证日志与实际操作一致。
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。
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预期输出:
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() 判断文件名是否可用。