Next.js 15.3.2集成Uploadthing：显示上传成功却触发404错误

问题情况 #

• 学习两年前发布的Code with Antonio LMS课程，使用Uploadthing上传图片时，返回的payload显示状态为uploaded，但请求http://localhost:3000/api/uploadthing时出现404错误。

路由文件配置 #

import { createRouteHandler } from "uploadthing/next";

import { ourFileRouter } from "./core";

// Export routes for Next App Router
export const { GET, POST } = createRouteHandler({
  router: ourFileRouter,

  // Apply an (optional) custom config:
  // config: { ... },
});

错误信息 #

payload: {"status":"uploaded","metadata":{"userId":"user_2wrRIa1P2wdMnAACnpxOc4hiDVn"},"origin":"https://sea1.ingest.uploadthing.com","file":{"url":"https://utfs.io/f/Dce7zkRgom6nUrk8duyOe91kDfyiNKaouW6hgZxSEFzpYJn8","appUrl":"https://utfs.io/a/8131c6rbjr/Dce7zkRgom6nUrk8duyOe91kDfyiNKaouW6hgZxSEFzpYJn8","ufsUrl":"https://8131c6rbjr.ufs.sh/f/Dce7zkRgom6nUrk8duyOe91kDfyiNKaouW6hgZxSEFzpYJn8","name":"454439273_468013692693485_7948648305382373860_n.jpg","key":"Dce7zkRgom6nUrk8duyOe91kDfyiNKaouW6hgZxSEFzpYJn8","size":83784,"type":"image/jpeg","customId":null,"fileHash":"88f51495e5d96931e60bd278d28f2cd6"}}
  fileKey: Dce7zkRgom6nUrk8duyOe91kDfyiNKaouW6hgZxSEFzpYJn8
  error: StatusCode: non 2xx status code (404 POST http://localhost:3000/api/uploadthing)
 POST /api/uploadthing?slug=courseImage 404 in 800ms

排查与解决步骤 #

• 确认路由文件路径
  两年前的课程大概率使用Next.js Pages Router，路由文件应放在pages/api/uploadthing.ts而非当前App Router的app/api/uploadthing/route.ts结构。检查项目目录结构，对应调整文件位置。
• 匹配Uploadthing版本
  当前createRouteHandler是App Router的新用法，旧版Uploadthing适配Pages Router的写法不同。要么降级Uploadthing到课程当时的版本（参考课程配套的package.json），要么按当前Uploadthing文档更新路由和客户端代码。
• 验证router中的slug定义
  错误请求带了?slug=courseImage，需确保./core导出的ourFileRouter中明确定义了该slug，示例配置如下：

  import { createFileRouter } from "uploadthing/next";
  import { uploadthing } from "./server";
  
  const courseImage = uploadthing({
    image: { maxFileSize: "4MB" },
  }).onUploadComplete(async ({ metadata, file }) => {
    // 自定义上传完成逻辑
  });
  
  export const ourFileRouter = createFileRouter({
    courseImage,
  });
  

• 重启开发服务器
  修改路由或依赖后，重启Next.js开发服务器，确保配置生效。

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