Node.js中如何使用fs Promise移动文件替代file.mv方法

问题描述 #

我有一个用于接收文件的Node.js服务端应用，客户端上传文件后需要执行多项处理操作，其中一项是将文件移动到最终存储目录。
此前我使用file.mv方法实现该功能，现在需要将相关函数改造为async异步形式。我发现fsPromises模块中不存在mv方法，查阅文档后认为fsPromises.rename可实现同等效果，文档说明Buffer是合法参数类型，但实际编写代码运行时持续报错。

已尝试的操作与对应报错 #

• 第一次尝试直接传入file对象调用：

  await fsPromises.rename(file, newDir)
  

  抛出ENOENT错误：

  {"errno":-2,"code":"ENOENT","syscall":"rename","path":"FILE NAME.txt","dest":"XXX"}
  

  注：目标路径XXX已在上一步骤中成功创建
• 打印file对象得到结构如下：

  {"name":"FILE NAME.txt","data":{"type":"Buffer","data":[XX,XX,XX,XX,XX...]},"size":60,"encoding":"7bit","tempFilePath":"","truncated":false,"mimetype":"text/plain","md5":"cfd5514321a15034355f895e52d69fac"}
  

• 第二次尝试传入file.data.data字段：

  await fsPromises.rename(file.data.data, newDir)
  

  抛出ERR_INVALID_ARG_TYPE类型错误。
• 第三次尝试仅传入file.name作为参数，再次抛出和第一次一致的ENOENT错误。
• 第四次尝试基于file.data创建Buffer对象后传入：

  let buf = Buffer.from(file.data);
    await fsPromises.rename(buf, newDir)
  

  依然报错，Node会将传入的Buffer识别为路径参数，而非文件内容。

核心诉求：如何正确实现原有file.mv(newDir, async function(err)写法的等效异步功能？

问题根因 #

你对fsPromises.rename的功能存在根本性误解：

• 这个方法的作用是操作文件系统中已经存在的实体文件，它接收的Buffer/字符串参数全都是文件路径，从来不是内存中的文件内容。文档里标注的Buffer类型支持，指的是允许传入Buffer编码的路径值，不是传文件二进制内容。
• 你之前用的file.mv是上传中间件（比如express-fileupload）封装的上层方法，会自动兼容两种上传模式：文件落盘到临时目录时执行移动操作，文件缓存在内存时直接执行写入操作，和原生fs.rename的能力不对等。
• 从你打印的file对象看，tempFilePath字段为空，说明当前上传配置是把文件直接存在内存里，磁盘上根本不存在对应的源文件，不管你传name还是传内容Buffer给rename，都不可能找到源文件，自然持续报ENOENT错误。

正确实现 #

最简方案（和原mv逻辑完全一致） #

你用的上传中间件本身就支持Promise形式调用，不需要自己用fs模块重写，直接await调用即可，注意目标路径必须拼上文件名，不能只传目录：

const path = require('path');
const fullTargetPath = path.join(newDir, file.name);
await file.mv(fullTargetPath);

自行用fsPromises实现的版本 #

如果要完全脱离中间件的mv方法自己实现，覆盖两种上传场景即可：

const fs = require('fs/promises');
const path = require('path');

async function moveUploadFile(file, targetDir) {
  const targetPath = path.join(targetDir, file.name);
  // 临时文件存在，走移动逻辑
  if (file.tempFilePath) {
    try {
      await fs.rename(file.tempFilePath, targetPath);
    } catch (err) {
      // 跨磁盘分区移动时rename会报错，降级为复制+删除
      if (err.code === 'EXDEV') {
        await fs.copyFile(file.tempFilePath, targetPath);
        await fs.unlink(file.tempFilePath);
      } else {
        throw err;
      }
    }
    return;
  }
  // 文件缓存在内存中，走直接写入逻辑
  if (file.data) {
    await fs.writeFile(targetPath, file.data);
    return;
  }
  throw new Error('上传文件对象格式非法');
}

// 调用示例
await moveUploadFile(file, newDir);

避坑提示 #

• 所有fs写入/重命名方法的目标路径必须是完整文件路径，不能只传目录，否则会触发路径或权限错误。
• 不要把文件内容Buffer传给rename方法，这个方法不会解析传入Buffer的内容作为文件数据。

内容的提问来源于stack exchange，提问作者djcaesar9114