常见问题与排错

49-1

新手最容易犯的错，是看到满屏红字就慌、然后到处乱改。先冷静读报错信息：它通常告诉你「什么错了、在哪一行、什么类型」。Nuxt 的开发服务器还有错误覆盖层（error overlay），直接把错误和堆栈摆在你面前。把它读懂，问题就解决了一半。

49-2

最常见的警告长这样：Hydration completed but contains mismatches 或 Text content does not match server-rendered HTML。

原因：服务端渲染出的 HTML 和客户端激活时生成的内容不一致。常见诱因：

• 在模板里用了 new Date()、Math.random() 这类「每次都不同」的值；
• 用了依赖浏览器的 API（window、localStorage）渲染内容；
• 服务端和客户端读取的时间/环境不一致。

解决：把只在客户端才确定的内容，放进 onMounted 之后，或用 <ClientOnly> 包裹：

<template>
  <ClientOnly>
    <p>{{ browserOnlyValue }}</p>
  </ClientOnly>
</template>

49-3

报错：Nuxt instance is unavailable 或类似的 nuxtApp 取不到。

原因：你在 Nuxt 上下文之外调用了组合式函数（如 useRoute、useRuntimeConfig）。比如把调用写在了模块顶层、普通函数体内、或在 await 之后脱离了同步上下文。

解决：保证组合式函数在组件/页面/插件的 setup 里同步调用（见第 36 章）。非 SFC 组件用 defineNuxtComponent 而非 defineComponent 包一层。

49-4

现象：明明文件在 app/components/ 或 app/composables/，却报找不到或没自动导入。

排查：

• 改了目录结构后，重启开发服务器，让 Nuxt 重新扫描并刷新 .nuxt/*.d.ts 声明文件；
• 确认文件确实在 app/ 下（Nuxt 4 约定），而不是根目录；
• 检查文件名是否符合约定（组合式函数以 use 开头）；
• 若你关闭了 imports.scan，自定义代码需要手动 import。

49-5

现象：图片、favicon.ico 等从 public/ 引用却 404。

排查：Nuxt 4 下 public/ 搬到了 app/public/。如果迁移时没搬，/favicon.ico 自然找不到。引用路径写法不变，只动文件位置。

export default defineNuxtConfig({
  app: {
    head: {
      link: [{ rel: 'icon', href: '/favicon.ico' }],
    },
  },
})

确保 favicon.ico 在 app/public/ 下。

49-6

现象：nuxi build 中途报错退出。

排查方向：

• 先读报错栈顶部，定位是哪个文件、哪行；
• 类型错误：跑 nuxi typecheck 单独查类型；
• 依赖冲突：删 node_modules + 锁文件后重装；
• 模块不兼容 Nuxt 4：去模块仓库看 issue 或 compatibilityVersion；
• 内存不足（大项目）：Node 默认堆可能不够，用 NODE_OPTIONS=--max-old-space-size=4096 nuxi build。

49-7

现象：部署后日志一堆 [Vue Router warn]: No match found for location...。

原因：跑生产服务时没设 NODE_ENV=production，依赖不会剥离开发期警告。

解决：启动前设 NODE_ENV=production（见第 46 章部署）。

49-8

• 浏览器 DevTools：看 Console、Network、Performance，定位运行时与性能问题。
• nuxt dev --inspect：开启 Node Inspector，在 Chrome DevTools 里断点调试服务端。
• sourcemap 配置：默认服务端构建开 sourcemap，客户端 dev 模式也开，便于映射到源码。
• Nuxt DevTools：Timeline、Assets、Render Tree、Inspect 帮你看清组件树、资源大小、文件求值时间。
• IDE 调试：VS Code / JetBrains 都能配置同时调试客户端（Chrome）与服务端（Node），断点打在 app/ 源码上。

49-9

上述报错在 Nuxt 3 与 4 都可能出现。Nuxt 4 因 app/ 约定，组件找不到、资源 404 这类问题常与「目录没搬对」相关；排错工具和调试方式双方一致。

49-10

再补几个高频问题：

• window is not defined / document is not defined：在服务端代码里（<script setup> 顶层、插件非 client 部分）用了浏览器 API。把它挪进 onMounted 或 .client 插件，或用 import.meta.client 判断。
• Cannot find module '#...'：别名路径写错，或 .nuxt 声明没刷新。重跑 nuxi dev，必要时删 .nuxt 再起。
• 报错栈指向打包后的代码（看不懂）：确认开了 sourcemap（dev 默认开），用 nuxt dev --inspect 在 Chrome DevTools 里断点，能直接映射到 app/ 源码。
• 依赖装了但类型报错：跑 nuxi typecheck 单独看类型，比在构建报错里翻快。

49-11

与其背下每一条报错，不如建立一套通用排错顺序：先看报错信息里「离你代码最近的那行」，那通常才是根因；再确认它发生在客户端还是服务端（带 window is not defined 的八成是服务端误用了浏览器 API）；然后想清楚最近改了什么——大多是刚加的依赖、刚改的 nuxt.config 或目录结构引起的；最后用最小化复现缩小范围（删掉可疑代码看还报不报）。养成「先看栈、再定位环境、最后二分法排查」的习惯，比搜半天报错文案更高效。

49-12

hydration 不匹配靠 <ClientOnly>/onMounted；Nuxt instance is unavailable 是上下文外调用组合式函数；找不到组件先重启 dev；资源 404 检查 app/public/；构建失败先定位类型/依赖/模块。下一章给你一份学习路径与生态资源地图。

49-8 构建报错的通用排查流程

遇到构建报错时，按以下流程排查能高效定位问题。第一步，仔细阅读错误信息的最后一行，通常那里有最直接的报错原因。第二步，看错误信息里提到的文件路径和行号，定位到具体的源码位置。第三步，检查最近修改的文件，大部分构建错误都是最近的代码改动引入的。

如果错误信息不够明确，尝试以下步骤：清除 .nuxt/ 和 node_modules/.cache/ 目录后重新构建；运行 npx nuxi prepare 重新生成类型定义；检查 nuxt.config.ts 是否有语法错误。

在团队项目中，如果只有你的机器构建失败而其他同事正常，问题通常出在本地环境：Node 版本不一致、依赖安装不完整、或者本地缓存损坏。试试删除 node_modules 和锁文件后重新安装。