如何在 Next.js 13 中正确接收并解析 URL 编码的表单数据

在 Next.js 13 的 App Router 架构中，服务端表单数据处理需通过 Route Handlers（路由处理器）实现，而非传统的中间件（Middleware）或 Pages Router 的 req.body。关键点在于：URL 编码表单数据不能通过 req.body 直接读取，而必须调用 req.formData() —— 即使 Content-Type 是 application/x-www-form-urlencoded，Next.js 也统一使用该方法解析所有表单类载荷（含 multipart/form-data 和 x-www-form-urlencoded）。

✅ 正确做法：使用 POST 路由处理器 + req.formData()

首先，在 app/submit/route.ts（注意路径为 app/[route]/route.ts）中创建路由处理器：

// app/submit/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  try {
    // ✅ 正确：统一使用 formData() 解析 URL 编码或 multipart 表单
    const formData = await req.formData();

    const username = formData.get('username')?.toString().trim();
    const password = formData.get('password')?.toString().trim();

    // 验证必填字段
    if (!username || !password) {
      return NextResponse.json(
        { error: 'Username and password are required' },
        { status: 400 }
      );
    }

    // ✅ 此处可进行密码哈希、数据库写入、JWT 签发等业务逻辑
    console.log('Received login attempt:', { username });

    return NextResponse.json(
      { message: 'Login processed successfully', user: { username } },
      { status: 200 }
    );
  } catch (error) {
    console.error('Form processing error:', error);
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

? 原理说明：req.formData() 是 Web Platform 标准 API，在 Next.js 中已被适配支持 x-www-form-urlencoded。它会自动解析请求体中的键值对（如 username=john&password=123），无需手动设置 bodyParser 或中间件解析。

⚠️ 常见误区与注意事项

• ❌ 不要在 Middleware 中尝试读取表单数据
  Middleware 运行于请求早期，不支持 await req.formData()，且 req.body 始终为空——这是设计限制，非 bug。

• ❌ 不要依赖 req.json() 或 req.text() 解析表单
  req.json() 仅适用于 application/json；req.text() 返回原始字符串，需手动解析（不推荐，易出错且不安全）。

• ✅ 确保表单 action 指向正确的 Route Handler 路径
  如上例中 <form action="/submit" method="post">，对应 app/submit/route.ts。路径必须精确匹配，区分大小写。

• ✅ 前端无需额外配置 Content-Type
  浏览器默认为 application/x-www-form-urlencoded，<form method="post"> 会自动设置，无需 JS 手动设置 headers。

?️ 安全与健壮性建议

• 始终对 formData.get() 返回值做空值检查与类型转换（.toString()）；
• 对敏感字段（如密码）立即进行哈希（推荐 bcrypt）并丢弃明文；
• 添加 CSRF 防护（如使用 next-auth 或自建 token 验证）；
• 生产环境务必启用 HTTPS，防止凭证明文泄露。

✅ 总结

在 Next.js 13 App Router 中接收 URL 编码表单数据，唯一标准方式是：
在 app/[path]/route.ts 中导出 POST 函数 → 调用 await req.formData() → 使用 .get(key) 提取字段。
摒弃 req.body 思维，拥抱 formData() 统一接口，既符合 Web 标准，又兼容各类表单编码格式，是现代 Next.js 表单处理的最佳实践。