Uppy 4与Companion 5集成Google Drive上传问题的技术解析

在使用Uppy 4.3.0与Companion 5.1.0版本时，开发者遇到了从Google Drive上传文件失败的问题。本文将深入分析问题原因，并提供完整的解决方案。

问题现象

当开发者将项目从Uppy 3和Companion 4升级到新版本后，发现Google Drive文件上传流程中断。具体表现为：

1. 文件能正常从Google Drive选择并进入onBeforeUpload回调
2. 但文件无法到达getUploadParameters阶段
3. Companion服务器端报错："s3: bucket key must be a string or a function resolving the bucket string"

根本原因分析

这个问题源于Uppy 4和Companion 5版本对S3上传流程的严格校验机制。在旧版本中，Companion可能对缺少S3配置的情况处理较为宽松，而新版本则强制要求完整的S3配置。

Companion的核心设计理念是避免将文件数据传输到客户端，以节省带宽。其工作流程是：

1. 客户端通过Companion获取文件元数据
2. 用户选择文件后，Companion直接从Google Drive下载文件
3. 文件通过Companion上传到目标存储（如S3）
4. 客户端仅接收上传结果，不处理文件数据

解决方案

要解决这个问题，需要在Companion配置中添加完整的S3凭证信息：

const options = {
  providerOptions: {
    drive: {
      key: COMPANION_GOOGLE_KEY,
      secret: COMPANION_GOOGLE_SECRET,
    },
  },
  s3: {
    bucket: 'YOUR_S3_BUCKET_NAME',
    key: 'YOUR_S3_ACCESS_KEY',
    secret: 'YOUR_S3_SECRET_KEY',
    region: 'YOUR_S3_REGION'
  },
  server: {
    host: "companion.example.com",
    protocol: "https",
    path: "/companion",
  },
  filePath: `${__dirname}/uploads`,
  secret: APP_SECRET,
};

React集成最佳实践

在React中使用Uppy时，建议遵循官方推荐模式，避免使用useRef+useEffect的组合。正确的做法是：

function UploadVideo({ onComplete }) {
  const uppy = useMemo(() => {
    const instance = new Uppy({
      restrictions: {
        maxNumberOfFiles: 1,
        minNumberOfFiles: 1,
        allowedFileTypes: ["video/*", "video/mp4"],
      },
      autoProceed: true,
    });
    
    instance.use(AwsS3, {
      shouldUseMultipart: () => false,
      getUploadParameters: async (file) => {
        // 获取上传参数逻辑
      }
    });
    
    instance.use(GoogleDrive, {
      companionUrl: "https://companion.example.com/companion",
    });
    
    return instance;
  }, []);

  return <Dashboard uppy={uppy} plugins={["GoogleDrive"]} />;
}

总结

Uppy 4和Companion 5版本对配置要求更加严格，特别是对于S3上传场景。开发者需要确保在Companion配置中提供完整的S3凭证信息，同时遵循React集成的最佳实践。这些改进虽然增加了配置的复杂度，但能提供更稳定和安全的文件上传体验。