Node.js / 系统课时
复制、移动与删除文件
复制、移动与删除文件
这一节把文件复制、重命名、移动和删除放进一条可验证的流程。你会使用 copyFile()、rename() 和 unlink() 完成常见文件管理,并处理“目标已存在”和“跨磁盘移动”这两个最容易踩坑的边界。
学习目标
- 使用
copyFile()复制文件,并控制目标已存在时是否允许覆盖。 - 使用
rename()完成同一文件系统内的重命名和移动。 - 使用
unlink()删除文件,并通过access()验证最终状态。
先选对文件操作 API
以下示例按 Node.js 22+ 的 node:fs/promises 写法演示。四类操作不要混用:复制保留源文件,重命名只改变路径名,移动改变所在目录,删除则让目录项消失。对于普通文件,可以按下面这张表直接选择 API。
| 需求 | API | 关键行为 |
|---|---|---|
| 复制文件 | copyFile(src, dest, mode) |
默认可覆盖;传 COPYFILE_EXCL 可在目标存在时失败 |
| 重命名 | rename(oldPath, newPath) |
同一文件系统内直接改路径 |
| 移动文件 | rename(oldPath, newPath) |
目标目录不同但仍在同一文件系统时同样适用 |
| 删除文件 | unlink(path) |
目标不存在通常抛出 ENOENT |
如果目标路径来自用户输入,应先用 join() 或 resolve() 统一构造路径,并限制在业务工作目录内。不要通过字符串拼接手写 / 或 \,否则跨 Windows、macOS 和 Linux 时更容易出现路径问题。
一段脚本完成复制、重命名、移动和删除
主示例先重建一个干净工作区,然后把 inbox/report.txt 复制到备份目录,再重命名源文件、移动到归档目录,最后删除备份。复制时使用 COPYFILE_EXCL,这样意外存在同名备份时会直接失败,而不是静默覆盖。
import {
access,
copyFile,
mkdir,
rename,
rm,
unlink,
writeFile
} from 'node:fs/promises';
import { constants } from 'node:fs';
import { join } from 'node:path';
const root = join(process.cwd(), 'file-op-demo');
const inbox = join(root, 'inbox');
const backup = join(root, 'backup');
const archive = join(root, 'archive');
await rm(root, { recursive: true, force: true });
await Promise.all([
mkdir(inbox, { recursive: true }),
mkdir(backup, { recursive: true }),
mkdir(archive, { recursive: true })
]);
const source = join(inbox, 'report.txt');
const backupFile = join(backup, 'report.txt');
await writeFile(source, 'version=1\n', 'utf8');
// COPYFILE_EXCL 防止已有备份被覆盖。
await copyFile(source, backupFile, constants.COPYFILE_EXCL);
console.log('copied: backup/report.txt');
const renamed = join(inbox, 'final-report.txt');
await rename(source, renamed);
console.log('renamed: inbox/final-report.txt');
const moved = join(archive, 'final-report.txt');
await rename(renamed, moved);
console.log('moved: archive/final-report.txt');
await unlink(backupFile);
console.log('deleted: backup/report.txt');
// 最后检查移动后的文件存在,而被删除的备份不存在。
for (const [label, path] of [
['moved target', moved],
['deleted backup', backupFile]
]) {
try {
await access(path);
console.log(`${label}: exists`);
} catch (error) {
console.log(`${label}: ${error.code}`);
}
}将代码保存为 file-operations.mjs 后运行:
node file-operations.mjs预期输出:
copied: backup/report.txt
renamed: inbox/final-report.txt
moved: archive/final-report.txt
deleted: backup/report.txt
moved target: exists
deleted backup: ENOENT运行后可以直接检查 file-op-demo/archive/final-report.txt,内容仍应是 version=1。backup/report.txt 应已不存在,这说明复制、改名、移动和删除四个步骤都按预期完成。
目标已存在时不要默认覆盖
copyFile() 不带模式时可以覆盖已有目标文件;备份、导出和用户上传场景通常更适合传 constants.COPYFILE_EXCL。如果目标已经存在,操作会失败,你可以提示用户改名,而不是悄悄覆盖旧文件。
rename() 对目标已存在时的行为还受操作系统和目标类型影响,因此不要把它当成通用的“安全覆盖”方案。需要保留历史版本时,先生成唯一文件名,例如 report-2026-10-03.txt,再执行复制或移动,逻辑会更明确。
跨文件系统移动要改成复制后删除
rename() 适合在同一文件系统内移动;如果源文件和目标目录位于不同磁盘、挂载点或某些容器卷之间,可能收到 EXDEV。这时正确顺序是:先 copyFile() 到目标,确认复制成功,再 unlink() 源文件,不能先删源文件再复制。
对于大文件,复制完成后还可以再读取源文件和目标文件的 stat().size 做一次字节数核对。若业务要求更强校验,再计算哈希;只有复制和校验都成功后才删除源文件。这样即使中途断电或目标磁盘写满,也不会因为过早删除而丢掉唯一副本。