GCS NodeJS TransferManager.UploadManyFiles的skipIfExists选项行为异常

一、修复TransferManager.UploadManyFiles()的skipIfExists问题 #

你遇到的skipIfExists不生效、批量上传遇已存在文件直接报错中断的问题，大概率是依赖版本bug或未正确处理错误回调导致。以下是可行的修复方案：

正确配置与错误处理示例 #

const { Storage, TransferManager } = require('@google-cloud/storage');
const storage = new Storage();
const bucket = storage.bucket('你的桶名称');
const transferManager = new TransferManager(bucket);

async function batchUploadWithSkip() {
  const fileList = [
    { source: './本地文件1.txt', destination: '远端文件1.txt' },
    // 其他待上传文件...
  ];

  const options = {
    skipIfExists: true,
    concurrency: 5 // 根据服务器性能调整并发数
  };

  try {
    const results = await transferManager.uploadManyFiles(fileList, options);
    
    // 统计上传结果
    const uploaded = results.filter(item => item.status === 'success');
    const skipped = results.filter(item => item.status === 'skipped');
    
    console.log(`成功上传 ${uploaded.length} 个文件`);
    console.log(`跳过 ${skipped.length} 个已存在文件`);
  } catch (err) {
    // 区分文件已存在的错误与其他异常
    if (err.code === 412 || err.message.includes('already exists')) {
      console.log('存在已跳过的文件，剩余文件已完成处理');
    } else {
      console.error('批量上传发生异常:', err);
    }
  }
}

batchUploadWithSkip();

关键注意事项 #

• 先执行npm update @google-cloud/storage升级依赖，老版本的skipIfExists确实存在中断批量任务的bug。
• 若升级后问题仍存在，建议改用手动批量处理：遍历文件列表，逐个判断存在性后上传，避免单个文件问题中断全局任务。

二、单文件上传的存在性判断实现 #

如果需要 fallback 到单文件上传场景，可通过两种方式实现跳过逻辑：

方案1：提前判断文件是否存在 #

async function uploadSingleFile(sourcePath, destPath) {
  const file = bucket.file(destPath);
  const [exists] = await file.exists();
  
  if (exists) {
    console.log(`文件 ${destPath} 已存在，跳过`);
    return { status: 'skipped', path: destPath };
  }
  
  try {
    await file.upload(sourcePath);
    return { status: 'success', path: destPath };
  } catch (err) {
    console.error(`文件 ${destPath} 上传失败:`, err);
    return { status: 'failed', path: destPath, error: err };
  }
}

// 批量调用单文件上传
async function batchUpload(fileList) {
  const results = await Promise.all(fileList.map(item => 
    uploadSingleFile(item.source, item.destination)
  ));
  
  const stats = {
    success: results.filter(r => r.status === 'success').length,
    skipped: results.filter(r => r.status === 'skipped').length,
    failed: results.filter(r => r.status === 'failed').length
  };
  
  console.log('批量上传统计:', stats);
  return results;
}

方案2：上传时捕获已存在错误（避免竞态） #

如果担心“判断存在性”和“上传”之间有其他进程修改文件，可直接上传并捕获预条件错误：

async function uploadSingleFileWithCatch(sourcePath, destPath) {
  const file = bucket.file(destPath);
  
  try {
    await file.upload(sourcePath, {
      // 预条件：仅当文件不存在时才上传
      preconditionOpts: { ifGenerationMatch: 0 }
    });
    return { status: 'success', path: destPath };
  } catch (err) {
    if (err.code === 412) {
      console.log(`文件 ${destPath} 已存在，跳过`);
      return { status: 'skipped', path: destPath };
    } else {
      console.error(`文件 ${destPath} 上传失败:`, err);
      return { status: 'failed', path: destPath, error: err };
    }
  }
}

三、最终建议 #

1. 优先升级@google-cloud/storage到最新版本，验证TransferManager的skipIfExists是否恢复正常。
2. 若批量上传仍中断，改用手动批量单文件上传的方式，确保每个文件的处理独立，不会因单个文件已存在而终止整个任务。
3. 无论采用哪种方式，都要收集每个文件的处理结果，方便后续统计和排查问题。

内容的提问来源于stack exchange，提问作者Judith Van Dongen