本文详解如何使用 node.js 的 promise api 正确实现文件批量复制，解决因异步操作未等待导致仅最后一个文件被复制的问题，并提供可生产使用的健壮代码示例。
本文详解如何使用 node.js 的 promise api 正确实现文件批量复制，解决因异步操作未等待导致仅最后一个文件被复制的问题，并提供可生产使用的健壮代码示例。
在 Node.js 中执行文件批量复制时，若直接使用回调函数（callback）配合 forEach 循环调用异步方法（如 fs.cp），极易陷入「伪同步」陷阱：所有复制任务被并发发起，但主流程不等待任一任务完成便立即退出，导致 count 统计失效、错误无法捕获、甚至部分文件静默失败。
根本原因在于：Array.prototype.forEach() 不识别 Promise，它只是同步地为每个元素调用回调函数，而不会暂停执行以等待 fs.cp 的异步操作结束。因此，console.log(count) 在所有 transferFiles() 调用发起后立刻执行，此时绝大多数复制尚未完成，count 仍为初始值（或仅累加了极少数已快速完成的任务）。
✅ 正确做法是统一采用 Promise 风格的异步 I/O，并通过 async/await 序列化执行流程。自 Node.js 10+ 起，fs.promises 提供了完整的 Promise 化 API，推荐替代回调式 fs 模块。
Json Schema Toolkit
下载
使用 JSON Schema 验证 JSON 数据，从示例 JSON 生成 schema，并将其转换为 TypeScript 接口、Python 数据类或 Markdown 文档。
以下是推荐的完整实现：
const fs = require('fs');
const fsp = fs.promises;
async function transferFiles(fileName) {
const src = `F:/Some Folder/Origin Folder/${fileName.trim()}`;
const dest = `F:/Some Folder/Target Folder/${fileName.trim()}`;
// 跳过空行和空白字符
if (!fileName.trim()) return;
try {
await fsp.cp(src, dest, { recursive: false }); // 若需复制目录，设 recursive: true
console.log(`✅ Transferred: ${fileName.trim()}`);
} catch (err) {
console.error(`❌ Failed to copy ${fileName.trim()}:`, err.message);
throw err; // 向上抛出，便于统一错误处理
}
}
async function readFileContents() {
let count = 0;
try {
const data = await fsp.readFile("F:/Some Folder/FileNames.txt", "utf8");
const fileNames = data.split("\n");
for (const fileName of fileNames) {
await transferFiles(fileName);
count++;
}
console.log(`? All done! Total files transferred: ${count}`);
return count;
} catch (err) {
console.error("❌ Failed to read file list:", err.message);
throw err;
}
}
// 使用示例（顶层调用）
readFileContents()
.then(total => console.log(`Success: ${total} files copied.`))
.catch(err => console.error("Operation aborted:", err));
? 关键要点与注意事项：
- ✅ 禁用 forEach 处理异步逻辑：永远不要在 forEach 中 await，它无法暂停循环；改用 for...of 或传统 for 循环。
- ✅ 清理文件名：使用 .trim() 剔除换行符 \n 和首尾空格，避免路径拼接错误（如 F:/.../Origin Folder/\n）。
- ✅ 错误防御：fs.cp() 默认不覆盖同名文件，若需覆盖，请传入 { force: true } 选项；同时建议添加 recursive: true 支持子目录（若源为文件夹）。
- ✅ 路径安全性：生产环境应校验 fileName 是否包含路径遍历字符（如 ../），防止任意文件写入漏洞。
- ✅ 性能权衡：上述代码为串行复制，确保顺序与可控性；如需提升吞吐量，可用 Promise.all() 并行执行，但需额外处理失败重试与进度统计。
通过 Promise + async/await 统一异步控制流，不仅能准确统计成功数量，还能实现清晰的错误传播、资源管理与调试体验——这才是 Node.js 文件操作的现代实践方式。
