Next.js Route Handlers 404 错误排查与正确配置指南

next.js 中 route handler 返回 404 的常见原因是 api 路由路径不匹配：`app/api/route.ts` 默认响应 `/api` 根路径，而客户端错误地请求了 `/app/api/ingresos`；需统一使用 `/api` 前缀，并通过子目录结构（如 `app/api/ingresos/route.ts`）实现语义化路由。

要解决 Next.js Route Handler 的 404 错误，关键在于严格遵循其文件系统路由约定：Route Handler 必须放置在 app/ 目录下的 api/ 子目录中，且每个处理函数必须位于以 route.ts（或 .js）命名的文件内，其所在目录路径即为最终暴露的 API 路径。

你当前的结构是：

app/
  api/
    route.ts   ← 此文件对应 /api（而非 /api/ingresos）

但你在表单中请求的是 /app/api/ingresos（错误前缀 + 错误路径），浏览器实际发起的是 GET http://localhost:3000/app/api/ingresos —— 这既多写了 /app（Next.js 自动挂载 app/ 下内容到根域），又将 ingresos 当作路径段却未在文件系统中体现。

✅ 正确做法如下：

Kacha

KaCha是一款革命性的AI写真工具，用AI技术将照片变成杰作！

下载

1. 调整文件结构：创建专用路由目录
   将 Route Handler 移至 app/api/ingresos/route.ts（注意不是 app/api/route.ts）：

   app/
     api/
       ingresos/
         route.ts   ← 此文件将响应 POST /api/ingresos

2. 修正客户端表单 action
   删除冗余的 /app 前缀，使用相对根路径：

   'use client';
   import { useState } from 'react';
   
   export default function EnviarIngresos() {
     // ...state setup...
   
     return (
       <form action="/api/ingresos" method="POST">
         <input name="fuente" required />
         <input name="cantidad" type="number" required />
         <input name="fecha" type="date" required />
         <button type="submit">Enviar</button>
       </form>
     );
   }

3. 更新 Route Handler 逻辑（推荐增强健壮性）
   app/api/ingresos/route.ts 示例：

   import { NextResponse } from 'next/server';
   import PocketBase from 'pocketbase';
   
   export async function POST(request: Request) {
     try {
       const body = await request.json();
       const { fuente, cantidad, fecha } = body;
   
       // 验证必要字段
       if (!fuente || cantidad == null || !fecha) {
         return NextResponse.json(
           { error: 'Faltan campos requeridos: fuente, cantidad o fecha' },
           { status: 400 }
         );
       }
   
       const pb = new PocketBase('http://127.0.0.1:8090');
       const record = await pb.collection('ingresos').create({
         fuente,
         cantidad: Number(cantidad),
         fecha,
       });
   
       return NextResponse.json(
         { message: 'Ingreso creado exitosamente', id: record.id },
         { status: 201 }
       );
     } catch (err) {
       console.error('Error al crear ingreso:', err);
       return NextResponse.json(
         { error: 'Error interno del servidor' },
         { status: 500 }
       );
     }
   }

⚠️ 注意事项：

• Route Handler 不支持 GET /api/ingresos 自动跳转到 POST：表单 method="POST" 会触发 POST 处理器，但若手动访问 /api/ingresos（无 method）则可能 405；如需支持多种方法，显式导出 GET、PUT 等函数。
• 确保 PocketBase 服务正在 http://127.0.0.1:8090 运行，且 ingresos 集合存在、字段名匹配。
• 开发时可通过 curl -X POST http://localhost:3000/api/ingresos -H "Content-Type: application/json" -d '{"fuente":"salario","cantidad":5000,"fecha":"2024-06-01"}' 手动测试接口。
• 若使用 App Router 表单提交后需重定向（避免重复提交），建议改用 useFormState 或 useFormStatus + redirect()（服务端重定向），或采用 fetch + event.preventDefault() 的客户端提交方式。

总结：Next.js Route Handler 的路径 = app/ 下 api/ 子目录的相对路径（不含 .ts），务必移除 URL 中多余的 /app，并确保目录结构与期望的 API 端点完全一致。这是 404 问题最常见、也最容易修复的根本原因。