Next.js与TypeScript中IncomingMessage无nextUrl属性问题排查

问题根源 #

你错误地将请求对象req的类型指定为Node.js原生的IncomingMessage，但这个类型并没有Next.js扩展的nextUrl属性。在Next.js的API路由中，请求对象是框架封装后的专属类型，而非原生Node.js请求类型。

分场景修正代码 #

1. App Router（Next.js 13+推荐） #

App Router的API路由需放在app/api/[路由名]/route.ts路径下，请求对象类型为NextRequest（来自next/server），修正后的代码如下：

import { NextRequest } from 'next/server';

export const GET = async (req: NextRequest) => {
    // TypeScript中建议用小写string而非大写String
    const matchString: string = req.nextUrl.searchParams.get("data") || '';
    // 示例返回逻辑
    return new Response(JSON.stringify({ receivedData: matchString }), { status: 200 });
}

2. Pages Router（旧版本路由系统） #

如果使用的是Pages Router，API路由放在pages/api/[路由名].ts，请求对象类型为NextApiRequest，此时获取查询参数用req.query而非nextUrl：

import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
    const matchString = req.query.data as string;
    res.status(200).json({ receivedData: matchString });
}

调试方法 #

• 确认路由类型：检查API路由所在目录，区分是App Router还是Pages Router，两者的请求类型完全不同。
• IDE类型提示：将鼠标悬停在req参数上，查看IDE给出的类型提示，确认正确的类型定义。
• 类型检查验证：运行npm run build或npx tsc --noEmit，让TypeScript帮你定位类型不匹配的问题。
• 依赖配置检查：确保已安装@types/node和typescript依赖，保证类型定义正常加载。

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