33. 调试技巧

本节目标：学会用 VS Code 和浏览器 DevTools 调试 Next.js 的客户端和服务端代码，掌握日志配置和常见错误排查方法。

VS Code 调试

VS Code 提供了强大的调试功能，可以同时在客户端和服务端设置断点。

配置 launch.json

在项目根目录创建 .vscode/launch.json：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Next.js: debug server-side",
      "type": "node-terminal",
      "request": "launch",
      "command": "npm run dev -- --inspect"
    },
    {
      "name": "Next.js: debug client-side",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000"
    },
    {
      "name": "Next.js: debug full stack",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/node_modules/next/dist/bin/next",
      "runtimeArgs": ["--inspect"],
      "skipFiles": ["<node_internals>/**"],
      "serverReadyAction": {
        "action": "debugWithEdge",
        "killOnServerStop": true,
        "pattern": "- Local:.+(https?://.+)",
        "uriFormat": "%s",
        "webRoot": "${workspaceFolder}"
      }
    }
  ]
}

四种调试模式

debug server-side：只调试服务端代码
debug client-side：只调试浏览器端代码
debug full stack：同时调试两端（推荐）
debug client-side (Firefox)：用 Firefox 调试

使用步骤

按 Ctrl+Shift+D（Mac 是 ⇧+⌘+D）打开调试面板
选择 “Next.js: debug full stack”
按 F5 启动
在代码中设置断点，触发相关逻辑时就会暂停

提示：如果改了端口号，记得把 http://localhost:3000 换成实际端口。

浏览器 DevTools

客户端代码调试

启动开发服务器后，在浏览器中：

Chrome：Ctrl+Shift+J（Mac 是 ⌥+⌘+I）打开 DevTools，切到 Sources 标签
Firefox：Ctrl+Shift+I 打开 DevTools，切到 Debugger 标签

按 Ctrl+P 可以搜索源文件。使用 Webpack 时文件路径以 webpack://_N_E/./ 开头；Next.js 16 默认使用 Turbopack，源文件路径格式可能不同，但同样可以通过 Ctrl+P 搜索。

服务端代码调试

要让浏览器 DevTools 能调试服务端代码，需要加 --inspect 标志：

npm run dev -- --inspect

终端会显示类似这样的信息：

Debugger listening on ws://127.0.0.1:9229/0cf90313-350d-4466-a748-cd60f4e47c95

然后在浏览器中：

Chrome：

打开 chrome://inspect
在 Remote Target 找到你的应用
点击 inspect

Firefox：

打开 about:debugging
点击 This Firefox
在 Remote Targets 找到应用，点击 Inspect

React Developer Tools

安装 React Developer Tools 浏览器扩展，可以：

查看组件树和 props/state
分析渲染性能
追踪 Hook 状态

这是 React 开发者必备的工具。

日志配置

Next.js 16 提供了灵活的日志配置，都在 next.config.ts 中设置：

请求日志

默认会打印所有请求，可以用正则忽略某些路径：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    incomingRequests: {
      ignore: [/\/api\/v1\/health/],
    },
  },
}

export default nextConfig

或者完全关闭：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    incomingRequests: false,
  },
}

export default nextConfig

Fetch 请求日志

开发时查看所有 fetch 请求的详细信息：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    fetches: {
      fullUrl: true, // 打印完整 URL
      hmrRefreshes: true, // 打印 HMR 缓存刷新
    },
  },
}

export default nextConfig

Server Function 日志

默认会打印每个 Server Function 的调用信息：

POST /
  └─ ƒ myAction(arg1, arg2) in 5ms app/actions.ts

可以关闭：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    serverFunctions: false,
  },
}

export default nextConfig

浏览器日志转发到终端

这个功能很实用，把浏览器的 console.log 转发到终端：

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: {
    browserToTerminal: true, // 转发所有日志
  },
}

export default nextConfig

可选值：

'warn'：只转发警告和错误（默认）
'error'：只转发错误
true：转发所有日志
false：关闭转发

转发时会带上源码位置：

[browser] Hello World (app/page.tsx:8:17)

完全关闭日志

// next.config.ts
import type { NextConfig } from 'next'

const nextConfig: NextConfig = {
  logging: false,
}

export default nextConfig

错误排查技巧

服务端错误

Next.js 错误界面底部有个 Node.js 图标，点击可以复制 DevTools URL，直接打开服务端调试器查看错误详情。

缓存问题排查

设置环境变量可以看到缓存命中情况：

NEXT_PRIVATE_DEBUG_CACHE=1

响应头 x-nextjs-cache 的值：

HIT：命中缓存
STALE：返回过期缓存，后台重新验证
MISS：未命中，重新渲染
REVALIDATED：按需重新验证

开发环境注意事项

Windows 用户如果遇到 Fast Refresh 很慢，检查 Windows Defender 是否关闭。它会对每次文件读取做扫描，严重影响性能。

JetBrains WebStorm 调试

WebStorm 用户配置更简单：

打开 Run > Edit Configurations
创建 JavaScript Debug 配置
URL 填 http://localhost:3000
运行后会同时启动 Node 应用和浏览器两个调试会话

实用调试技巧总结

服务端用 console.log：最简单直接，日志会出现在终端
客户端用 debugger：在代码中写 debugger 语句，DevTools 打开时会自动暂停
网络请求用 Network 面板：查看所有请求的详情和时序
React 组件用 React DevTools：查看 props、state 和渲染次数
性能问题用 Performance 面板：录制和分析运行时性能

调试是开发的基本功。花时间熟悉这些工具，能帮你节省大量排查问题的时间。