UploadThing 文件上传回调问题解析与解决方案

问题背景

在使用UploadThing进行文件上传时，开发者可能会遇到onUploadComplete回调函数无法正确返回元数据和文件数据的问题。这种情况通常表现为文件已成功上传至UploadThing仪表盘，但客户端却无法接收到上传完成后的响应数据。

问题现象

具体表现为：

1. 文件上传过程看似成功完成
2. 文件确实出现在UploadThing仪表盘中
3. 但onUploadComplete回调函数未被触发
4. 网络请求长时间停留在"发送响应"状态
5. 控制台无错误提示，但缺少预期的日志输出

根本原因分析

经过技术团队深入排查，发现此问题主要由以下两个因素导致：

1. 回调URL配置错误：在createRouteHandler配置中，开发者设置的callbackUrl缺少必要的路径部分（/api/uploadthing），导致上传服务无法正确回传数据。

2. 协议不一致问题：当不显式设置callbackUrl时，系统会自动推断协议（http/https），但推断结果可能与实际环境不符，特别是当NEXT_PUBLIC_URL使用https而系统推断为http时，会导致回调失败。

解决方案

1. 修正回调URL配置

确保在createRouteHandler配置中正确设置完整的回调URL：

export const { GET, POST } = createRouteHandler({
    router: ourFileRouter,
    config: {
        logLevel: "All",
        callbackUrl: process.env.NEXT_PUBLIC_URL + "/api/uploadthing",
    },
});

2. 协议一致性检查

检查并确保：

• 环境变量NEXT_PUBLIC_URL使用的协议（http/https）与实际部署环境一致
• 如果使用反向代理，确保x-forwarded-proto头部正确传递

3. 中间件排查

虽然在此案例中中间件不是问题原因，但建议开发者：

• 检查Next.js中间件配置，确保没有意外拦截上传API路由
• 使用简单的测试端点验证中间件影响

最佳实践建议

1. 显式配置回调URL：避免依赖自动推断，明确指定完整的回调URL
2. 环境变量管理：统一环境变量中的协议使用，保持开发与生产环境一致
3. 日志记录：在关键节点添加日志，帮助快速定位问题
4. 错误处理：完善错误处理逻辑，提供有意义的用户反馈

技术原理深入

UploadThing的上传流程包含以下几个关键阶段：

1. 客户端初始化上传请求
2. 服务器生成预签名URL
3. 客户端直接上传文件到存储服务
4. 存储服务完成上传后回调应用服务器
5. 应用服务器触发onUploadComplete回调
6. 结果返回给客户端

其中第4步的回调过程依赖于正确配置的回调URL。如果URL不完整或协议不匹配，将导致整个回调链断裂，虽然文件上传成功，但客户端无法获知最终状态。

总结

文件上传回调问题通常源于配置细节的疏忽。通过正确设置回调URL、确保协议一致性以及合理配置中间件，可以避免此类问题。作为开发者，应当重视配置的完整性和环境的一致性，同时建立完善的日志和监控机制，以便快速发现和解决类似问题。