Next.js 15 App Router本地构建失败：读取'query'未定义，Vercel正常

我正在开发一个基于Next.js 15 App Router的项目，其中包含一个POST类型的API路由，路径为app/api/users/webhook/route.ts。该项目在Vercel生产环境中构建及API路由运行均正常，但本地执行npm run build时出现以下错误：

TypeError: Cannot read properties of undefined (reading 'query')
    at new nH (.next/server/app/api/users/webhook/route.js:40:4398)
    at nJ.createSession (...)
    ...
Error: Failed to collect page data for /api/users/webhook

package.json #

本地使用bun环境，CI和Vercel环境使用npm，scripts配置如下：

"scripts": {
  "build": "next build",
  ...
}

排查与修复方向 #

• 检查顶层代码对请求上下文的访问：Next.js构建阶段会静态分析代码，如果route.ts的顶层作用域（而非POST处理函数内部）直接访问request.query这类需要运行时上下文的属性，就会触发该错误。所有依赖请求对象的逻辑必须移到请求处理函数内部。
• 排查会话/中间件库的初始化逻辑：错误栈中的createSession方法可能在构建阶段就被实例化，且内部尝试访问未定义的query属性。确保这类需要上下文的实例化操作放在POST函数内部执行。
• 同步依赖版本：本地bun环境和Vercel的npm环境可能存在依赖版本差异，执行npm install生成统一的package-lock.json后再用bun安装，消除版本不一致导致的构建行为差异。

代码示例修正 #

错误写法（顶层访问请求上下文）：

// 构建阶段request未定义，直接访问会报错
const query = request.query;

export async function POST(request: Request) {
  // ...
}

正确写法（处理函数内访问）：

export async function POST(request: Request) {
  // 用URL对象解析查询参数替代request.query
  const { searchParams } = new URL(request.url);
  const targetParam = searchParams.get('target');
  
  // 会话初始化移到函数内部
  const session = await createSession(request);
  // ...
}

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