Nuxt.js SSR模式下页面初始加载时如何渲染自定义错误页面？

开发者阿泽

2026-9-24

问题根因

你遇到的是Nuxt应用初始化/SSR阶段抛出错误时，自定义错误页未触发的典型场景：自定义props: ['error']的错误页仅能捕获Nuxt应用实例完成初始化之后抛出的运行时错误，比如nuxt-link跳转时的客户端路由错误。如果错误发生在服务端渲染阶段、插件加载阶段、应用根组件初始化阶段，会直接触发Nuxt内置的默认错误页。
你提到的Cannot read properties of undefined (reading 'innerWidth')报错本身就是典型的SSR阶段错误：innerWidth是浏览器端window对象的属性，服务端渲染时没有window对象，代码在服务端执行时直接抛出异常，此时自定义错误页还未完成初始化，自然不会渲染。

解决方案

1. 先确认错误页路径配置正确

Nuxt 2 自定义错误页必须放在layouts/error.vue
Nuxt 3 全局自定义错误页必须放在项目根目录的error.vue，放在layouts目录下不会全局生效
错误页必须仅声明props: ['error']作为入参，不要额外引入会导致初始化失败的依赖

2. 修复SSR阶段的客户端API调用错误

所有调用浏览器端API的逻辑必须加客户端执行判断：

// 选项式API写法
if (process.client) {
  console.log(window.innerWidth)
}

// 组合式API写法
import { onMounted } from 'vue'
onMounted(() => {
  console.log(window.innerWidth)
})

如果是插件中用到了客户端API，给插件文件加.client后缀，比如plugins/xxx.client.js，该插件只会在客户端执行，避免服务端报错。

3. 增加全局错误捕获兜底

在nuxt.config中配置全局错误处理，兜底捕获初始化阶段的异常：

// nuxt.config.ts 示例（Nuxt3）
export default defineNuxtConfig({
  app: {
    errorHandler: (error) => {
      console.error('全局异常捕获：', error)
    }
  }
})