Nuxt 3 集成 Vuetify 3 开启 SSR 报错原因及解决方法

问题场景 #

使用最新版Nuxt 3和Vuetify，手动配置了plugins/vuetify.ts和nuxt.config.ts：

plugins/vuetify.ts #

import { createVuetify } from 'vuetify'
import * as components from 'vuetify/components'
import * as directives from 'vuetify/directives'

export default defineNuxtPlugin(nuxtApp => {
  const vuetify = createVuetify({
    ssr: true,
    components,
    directives,
  })

  nuxtApp.vueApp.use(vuetify)
})

nuxt.config.ts #

export default defineNuxtConfig({
  ssr: true,
  build: {
    transpile: ['vuetify']
  },
  vite: {
    define: {
      'process.env.DEBUG': false
    }
  }
})

开启SSR后控制台报错：

[nuxt] error caught during app initialization H3Error: Page not found: /_nuxt/node_modules/vuetify/src/util/defineComponent.tsx

报错原因 #

该错误是因为Nuxt在SSR模式下未正确转译Vuetify的TSX源码文件，导致服务器端尝试直接访问未编译的vuetify/src目录下的文件——这些源码文件并未被打包到客户端可访问的静态资源路径中，因此触发404错误。

修复方案 #

方案一：优化手动配置的转译规则 #

修改nuxt.config.ts，补充必要的转译依赖并调整Vite解析规则：

export default defineNuxtConfig({
  ssr: true,
  build: {
    // 补充Vuetify相关的转译依赖
    transpile: ['vuetify', '@vuetify/loader-shared']
  },
  vite: {
    define: {
      'process.env.DEBUG': false
    },
    // 强制Nuxt解析Vuetify的编译后文件而非源码
    resolve: {
      alias: {
        'vuetify': 'vuetify/lib'
      }
    }
  }
})

方案二：使用官方Nuxt-Vuetify模块（更推荐） #

官方模块会自动处理SSR、转译等配置，无需手动编写插件：

1. 安装模块：

npm install @nuxtjs/vuetify

2. 修改nuxt.config.ts：

export default defineNuxtConfig({
  ssr: true,
  // 引入Vuetify模块
  modules: ['@nuxtjs/vuetify'],
  // 配置Vuetify（按需开启组件、指令等）
  vuetify: {
    ssr: true,
    components: true,
    directives: true
  }
})

3. 删除手动创建的plugins/vuetify.ts文件。

额外注意 #

确保Nuxt 3和Vuetify均为最新稳定版本，避免版本兼容问题。

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