如何调试Next.js 13路由问题？日志与断点调试方法咨询

一、增强服务器日志，追踪路由决策过程 #

1. 启用内置调试日志 #

启动开发服务器时添加DEBUG环境变量，指定输出Next.js相关调试日志，能清晰看到路由匹配、请求分发的全流程：

DEBUG=next:* npm run dev

重点关注next:router和next:server前缀的日志，里面包含请求路径匹配的尝试过程、最终匹配的路由文件，以及未匹配时的原因说明。

2. 自定义中间件日志 #

在项目根目录创建src/middleware.ts，针对API路由添加日志追踪，实时监控每个请求的流转细节：

import { NextRequest, NextResponse } from 'next/server';

export function middleware(request: NextRequest) {
  console.log(`[API 请求追踪] 方法: ${request.method}，路径: ${request.nextUrl.pathname}`);
  console.log(`[路由匹配详情] 完整URL: ${request.nextUrl.href}，查询参数:`, request.nextUrl.searchParams);
  return NextResponse.next();
}

// 仅对API路由生效，避免日志冗余
export const config = {
  matcher: '/api/:path*',
};

二、断点调试请求处理流程 #

1. VS Code 可视化调试 #

在VS Code中创建.vscode/launch.json，配置Next.js开发服务器的调试环境：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js Dev 调试",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev",
      "serverReadyAction": {
        "pattern": "started server on .+, url: (https?://.+)",
        "uriFormat": "%s",
        "action": "debugWithChrome"
      }
    }
  ]
}

配置完成后，直接在route.ts文件的代码行号左侧点击添加断点，启动调试后，请求触发时会自动停在断点处，可逐步查看变量、调用栈，追踪请求处理的每一步。

2. Node.js 原生调试器 #

用--inspect参数启动Next.js，通过Chrome DevTools连接调试：

node --inspect node_modules/.bin/next dev

打开Chrome浏览器访问chrome://inspect，点击"Configure"添加本地调试地址（默认localhost:9229），然后在Sources面板中找到项目的route.ts或Next.js内部的服务器处理文件，设置断点即可调试。

注意事项 #

虽然App Router的官方调试文档较少，但核心逻辑和Page Router相通，调试时重点关注两个阶段：

• 路由匹配阶段：通过日志确认请求是否命中目标route.ts
• 请求处理阶段：通过断点追踪route.ts中的代码执行流程

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