NextJS 14升级至15（App Router）静态路由类型错误求助

问题概述 #

在Windows环境下通过App Router将NextJS从14升级到15后，某静态路由的POST接口在开发环境（npm run dev）运行正常，但执行npm run build时类型检查环节报错，提示自定义Context类型与Next.js内置的RouteContext不兼容。

代码与报错信息 #

原代码 #

interface Context {
  data: object;
  params: any;
}

export async function POST(request: NextRequest, context: Context) {
  const testBody = await request.json();
  // ...函数后续代码
}

构建报错 #

PS C:\Users\SJ\Desktop\nextjsProject> npm run build

> build
> next build

   ▲ Next.js 15.0.3
   - Environments: .env

   Creating an optimized production build ...
 ✓ Compiled successfully
   Linting and checking validity of types  ..Failed to compile.

.next/types/app/api/myRoute/route.ts:166:7
Type error: Type '{ __tag__: "POST"; __param_position__: "second"; __param_type__: Context; }' does not satisfy the constraint 'ParamCheck<RouteContext>'.
  Types of property '__param_type__' are incompatible.
    Property 'params' is missing in type 'Context' but required in type 'RouteContext'.

  164 |     Diff<
  165 |       ParamCheck<aRouteContext>,
> 166 |       {
      |       ^
  167 |         __tag__: 'POST'
  168 |         __param_position__: 'second'
  169 |         __param_type__: SecondArg<MaybeField<TEntry, 'POST'>>

已尝试无效的方法 #

• 从POST方法中移除context参数
• 将Interface Context的params类型改为Promise<string>和Promise<any>
• 将Interface Context改为type Context
• 将参数从context : Context改为context: {params: Promise<any>}
• 查阅NextJS迁移文档并尝试相关建议

解决方案 #

1. 使用正确的静态路由Context类型 #

静态路由无动态参数，因此context的params应为空对象类型，且Next.js的API路由context仅包含params字段，无需自定义data字段。修改代码如下：

import { NextRequest } from 'next/server';

// 静态路由专属context类型：params为空对象
type StaticRouteContext = { params: Record<string, never> };

export async function POST(request: NextRequest, context: StaticRouteContext) {
  const testBody = await request.json();
  // 若不需要params，可直接解构忽略：
  // export async function POST(request: NextRequest, { params }: StaticRouteContext) {
  // ...函数后续代码
}

2. 移除context参数并清理缓存 #

若完全不需要context参数，移除后需清理Next.js类型缓存以避免残留校验问题：

• 删除项目根目录下的.next文件夹
• 执行npm run build重新构建

3. 利用TypeScript自动推断类型 #

无需显式自定义类型，直接让TypeScript自动匹配Next.js的标准context结构：

import { NextRequest } from 'next/server';

export async function POST(request: NextRequest, context: { params: {} }) {
  const testBody = await request.json();
  // ...函数后续代码
}

问题根源 #

Next.js 15对App Router API路由的类型校验进行了强化：

• 无论是否为动态路由，API路由的context参数必须符合内置RouteContext结构
• 静态路由的params必须是空对象类型（Record<string, never>），自定义Context中params: any不符合该约束，且额外添加的data字段不属于标准context结构

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