如何快速定位Next.js项目运行时出现的代码错误？

1. 先区分报错所属环境 #

服务端运行的代码（SSR/SSG/服务端组件/服务端函数等）报错只会出现在项目启动的终端中，客户端代码报错会同时出现在浏览器控制台和终端。优先查找和你的项目路径一致的栈信息，忽略next/dist等框架本身的路径前缀行即可快速定位到自己的代码位置。

2. 开启源码映射提升报错精度 #

开发环境默认开启源码映射，生产环境可在next.config.js中添加配置开启源码映射，方便线上问题定位：

/** @type {import('next').NextConfig} */
const nextConfig = {
  productionBrowserSourceMaps: true,
}

module.exports = nextConfig

3. 利用框架自带错误边界捕获全链路报错 #

Pages Router 项目 #

根目录下新建pages/_error.js，在组件内打印完整错误栈即可溯源：

function Error({ statusCode, error }) {
  // 开发环境下直接在控制台打印完整错误栈
  if (process.env.NODE_ENV === 'development') {
    console.error('完整错误栈：', error.stack)
  }
  return <p>{statusCode ? `服务端错误 ${statusCode}` : '客户端错误'}</p>
}

Error.getInitialProps = ({ res, err }) => {
  const statusCode = res ? res.statusCode : err ? err.statusCode : 404
  return { statusCode, error: err }
}

export default Error

App Router 项目 #

在对应路由层级下新建error.js捕获当前路由及子路由错误，根目录新建app/global-error.js捕获全局错误，同样可在组件内打印错误栈：

'use client' // 错误边界必须标记为客户端组件

export default function Error({ error, reset }) {
  console.error('当前路由错误栈：', error.stack)
  return <div>出错了</div>
}

4. 特殊场景报错定位方法 #

• 服务端函数（getServerSideProps/generateStaticParams/服务端Action等）报错：直接在函数内添加try/catch捕获，手动打印错误栈即可
• Hydration不匹配报错：优先检查是否存在服务端和客户端渲染内容不一致的逻辑，比如直接调用window属性、时间相关渲染逻辑，可通过注释局部组件快速定位问题组件
• 第三方依赖报错：如果错误栈指向第三方包，可在next.config.js中配置transpilePackages将对应依赖转译，避免编译后代码无法溯源的问题

5. 断点调试进阶定位 #

可以通过VS Code断点调试直接在代码中打断点排查问题，新建.vscode/launch.json添加如下配置后即可启动调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    }
  ]
}

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