PAYATHON 2026

UploadThing 上传时提示 url 和 appUrl 弃用，需要修改什么？

数据小陈

将业务代码中使用的上传结果字段 data.url 和 data.appUrl 改为 data.ufsUrl，utapi.uploadFiles([file]) 调用可以保留。日志中的 error: null 表明这次上传成功，弃用告警本身不代表上传失败。

即使业务代码没有显式读取旧字段，也会收到告警。在 uploadthing@7.7.4 中，SDK 构造返回结果时会在内部读取这两个字段。

为什么 uploadFiles() 内部会触发告警？

在 7.7.4 的上传实现中，内部响应对象为 url 和 appUrl 定义了 getter。读取这两个属性时，getter 会输出弃用告警。随后，SDK 在 uploadFile() 中通过以下代码构造返回值：

url: response.url,
appUrl: response.appUrl,
ufsUrl: response.ufsUrl,

前两次属性读取触发了 getter，因此告警会在 await utapi.uploadFiles([file]) 返回之前出现。这条调用链可以在该版本的 upload-server.ts 和 sdk/utils.ts 中核对。

删掉后面的 console.dir() 不能消除这个版本中由 SDK 内部读取触发的告警。调用结束后再挑选 ufsUrl，也无法撤回已经输出的告警。

业务代码应如何修改？

弃用通知针对上传结果中的 URL 字段。7.7.4 的类型定义将 url 和 appUrl 标记为弃用，注明将在 v9 移除，替代字段为 ufsUrl。这项声明没有将 uploadFiles() 标记为弃用。参见 UploadedFileData 定义。

保留原有的文件读取和 File 创建代码，将上传及结果处理部分替换为：

const res = await utapi.uploadFiles([file]);

for (const { data, error } of res) {
  if (error) {
    throw new Error(`Upload failed: ${error.message}`);
  }

  if (!data) {
    throw new Error("Upload returned no file data");
  }

  results.push({
    file: filePath,
    result: {
      key: data.key,
      name: data.name,
      ufsUrl: data.ufsUrl,
    },
  });

  console.log(`Uploaded: ${filePath}`);
  console.log(`URL: ${data.ufsUrl}`);
}

传入的是 [file] 数组，因此返回值也按数组处理。这一行为在 UTApi 文档 中有说明。

示例显式保存了需要的字段，方便后续代码使用文件地址时只依赖 ufsUrl。如果其他代码也会保存文件地址或生成下载链接，检查它们是否读取了上传结果中的 url 或 appUrl。不要全局替换所有名为 url 的属性，其他 API 的同名参数可能有不同用途。

是否需要升级 uploadthing？

先确认实际安装版本：

npm ls uploadthing

"uploadthing": "^7.7.4" 表示允许安装的版本范围。实际使用的版本还受锁文件和安装结果影响，不能只凭这行声明认定正在运行 7.7.4。

如果希望更新到当前声明范围内可用的版本，可以执行：

npm update uploadthing

更新后重新检查版本，运行原来的上传脚本。内部告警是否消除，要看目标版本的实现和实际运行结果，无法保证每次升级都能修复。

对于已确认的 7.7.4 内部触发路径，业务代码改用 ufsUrl 可以完成字段迁移，但仍可能看到 SDK 自身输出的告警。要消除这部分告警，需要使用调整了该内部实现的版本。告警中提到的 v9 是旧字段的移除计划，不意味着必须立即升级到 v9。

备注：内容仅供参考。