Nuxt 4 开发服务器与热更新：HMR、错误覆盖层及调试技巧

本节目标：用 nuxi dev 启动开发服务器，理解热更新（HMR）是什么，看懂报错时弹出的错误覆盖层，并知道怎么在浏览器和编辑器里调试。

写代码的过程中，你绝大部分时间都泡在「开发模式」里。Nuxt 的开发服务器不只是把页面跑起来，它还带了热更新、实时代码检查和友好的报错界面。这一章把这些都讲透。

5-1

进入项目目录后，运行：

# npm
npm run dev

# pnpm
pnpm dev

# 想启动后自动打开浏览器
npm run dev -- -o

dev 命令背后调用的是 nuxi dev。启动成功后，终端会打印本地地址，默认是 http://localhost:3000。在浏览器打开它，就能看到你的应用。

Tip

-- -o 这种写法，意思是把 -o 参数透传给 nuxi（打开浏览器）。用 pnpm 时直接 pnpm dev -o 即可，不需要 --。

5-2

HMR 是 Hot Module Replacement（热模块替换）的缩写。它的好处是：你改完代码、保存文件的瞬间，浏览器里的内容就自动刷新成新版本，不需要手动刷新页面，也不需要整页重新加载。

想象你在调一个表单组件，改一处样式就要刷新整页、重新填一遍表单，那会非常折磨。HMR 只替换「改动的那一小块」，页面状态（比如你填到一半的输入框）还能保留。Nuxt 默认用 Vite 做构建工具，HMR 开箱即用，你什么都不用配。

Note

HMR 偶尔会「失手」——比如改了全局配置 nuxt.config.ts，这种改动 Vite 无法热替换，Nuxt 会自动重启整个开发服务器（终端里能看到重启日志）。这是正常现象，不是报错。

5-3

开发时最怕的是「代码写错了，但不知道错在哪」。Nuxt 在这方面很贴心：一旦运行时出现错误，浏览器页面会盖上一层错误覆盖层，直接把问题摆在你面前。

覆盖层里通常包含：

错误信息（红色那行，最关键）
出错的文件和行号
一条调用栈（stack trace），告诉你错误是从哪一层一层传过来的

举个例子，如果你在 <script setup> 里拼错了一个变量名，保存后页面会立刻变红，告诉你「XXX is not defined」，并标出是哪个文件的哪一行。

Warning

错误覆盖层只在开发模式出现。构建产物（生产环境）不会显示它，而是走你配置的正式错误页。所以开发时遇到红线别慌，它是在帮你，认真读那行错误信息往往就能定位问题。

5-4

最常用的调试入口就是浏览器自带的开发者工具（按 F12 打开）。你可以：

在 Console（控制台） 看运行时报错和打印的日志（console.log）。
在 Network（网络） 看每个请求的响应，排查接口问题。
在 Elements（元素） 看最终渲染出的 HTML 结构。

Nuxt 默认开启了 sourcemap（源码映射），意味着你在开发者工具里看到的代码，能对应回你写的 .vue 源文件，而不是打包后的乱码。

5-5

如果你要调试服务端代码（比如 server/api/ 里的接口），需要 Node 的调试器。启动开发服务器时加 --inspect：

nuxt dev --inspect

这会在调试模式下启动，Chrome 的开发者工具里会出现一个 Node 图标，点开就能给服务端代码下断点、单步执行。

Important

Node 调试器要求 Node 进程和 Chrome 在同一台机器上运行，在 Docker 容器里这种方式不生效。本地开发直接用就好。

5-6

想要更顺手的体验，可以在 VS Code 里配置调试。最常见的做法是编辑 .vscode/launch.json，加入一个「启动 Chrome 并附加到 localhost:3000」的配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "chrome",
      "request": "launch",
      "name": "client: chrome",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/app"
    },
    {
      "type": "node",
      "request": "launch",
      "name": "server: nuxt",
      "program": "${workspaceFolder}/node_modules/nuxt/bin/nuxt.mjs",
      "args": ["dev"]
    }
  ]
}

注意 webRoot 指向 app 目录——这正是 Nuxt 4 的 srcDir。配好后按 F5，编辑器就能直接在 .vue 文件里下断点，比在浏览器里翻方便得多。

5-7

默认情况下，开发模式的客户端构建是带 sourcemap 的，服务端构建也默认开启。如果你想更精细地控制，可以在 nuxt.config.ts 里写：

export default defineNuxtConfig({
  sourcemap: {
    server: true,
    client: true,
  },
})

sourcemap: true 是同时开启两端的简写。一般不用动，知道有这个选项即可。

5-8

HMR 大部分时候很乖，偶尔也会「失手」，常见几种情况和应对：

改 nuxt.config.ts 或大结构：这类改动 Vite 没法热替换，Nuxt 会整体重启开发服务器（终端有日志），等它重启完刷新即可。
改了 .env 或 runtimeConfig：环境变量在启动时读一次，运行时改了不生效，得手动停掉 dev 重跑。
样式死活不更新：多半是浏览器缓存，硬刷新一下（Ctrl+F5）通常就好。
整个页面卡住不动：偶尔 HMR 状态乱了，在终端按 Ctrl+C 停掉、重新 npm run dev 是最彻底的救济。

Warning

如果你发现「明明改了代码，页面还是旧的」，先确认终端里开发服务器还在跑、且当前目录就是你改的那个项目。很多次「没生效」其实是改错了文件夹，或服务器早就自己退出了。

5-9

默认端口是 3000。万一被别的程序占了（比如另一个 Nuxt 项目没关），启动时加 --port 换一个：

npm run dev -- --port 4000

也可以直接在 nuxt.config.ts 里固定端口，省得每次手敲：

export default defineNuxtConfig({
  devServer: {
    port: 4000,
  },
})

Tip

同时跑多个 Nuxt 项目时，给每个配不同端口最省事，避免互相抢 3000。

5-10

npx nuxi dev（即 npm run dev）启动开发服务器，HMR 让改动即时生效，错误覆盖层把 bug 直接指给你看。需要深入排查时，浏览器开发者工具、nuxt dev --inspect、以及编辑器断点三种方式任选。下一章我们看怎么把项目「打包」成可上线的产物。

5-10 开发模式下的性能提示

开发服务器在启动时会做一次完整构建，后续修改只增量编译改动部分。项目越大，首次启动越慢，这是正常现象。一般来说，几十个页面的项目在十秒内启动算正常；如果超过三十秒，可能需要检查机器性能或依赖数量。

开发过程中，保持终端窗口不要关闭。关闭终端等于停掉开发服务器，浏览器里的页面也会随之无法访问。如果你需要同时做其他事，可以新开一个终端窗口。另外，node_modules 文件夹不要手动删除或修改，否则开发服务器会报错。如果确实需要重装依赖，先停掉服务器，删掉 node_modules 和 package-lock.json（或 pnpm-lock.yaml），再重新安装。