Nuxt3集成threejs/troisjs部署Vercel出现ES模块加载错误如何解决

1. 配置Nuxt转译非兼容模块 #

修改项目根目录下的nuxt.config.ts，将troisjs和three加入转译列表，强制Nuxt构建时处理这两个包的模块兼容问题，同时指定SSG部署预设：

export default defineNuxtConfig({
  // 保留你现有其他配置
  build: {
    transpile: ['troisjs', 'three']
  },
  nitro: {
    preset: 'vercel-static'
  },
  // 可选：指定troisjs的ESM入口，避免模块解析错误
  alias: {
    'troisjs': 'troisjs/build/trois.es.js'
  }
})

2. 包裹3D组件为客户端专属 #

你的3D头部组件依赖浏览器WebGL能力，必须用Nuxt提供的<ClientOnly>标签包裹，避免SSG预渲染阶段（服务端环境）加载浏览器专属模块导致解析错误：

<template>
  <!-- 页面中调用3D组件的位置 -->
  <ClientOnly fallback="Loading 3D scene...">
    <Your3DHeaderComponent />
  </ClientOnly>
</template>

3. 修正troisjs导入语法 #

不要使用全量导入的写法，改为按需导入你需要的组件，即可解决Mesh导出找不到的问题：

<script setup>
// 错误写法：import * as Trois from 'troisjs'
import { Renderer, Scene, Mesh, PerspectiveCamera, OrbitControls } from 'troisjs'
// 剩余你的组件逻辑
</script>

4. （可选）永久修复troisjs的模块配置 #

如果上述配置依旧提示模块规范相关错误，可以用包管理器的补丁功能固化troisjs的package.json修改，不需要手动改node_modules，部署时会自动生效：

• 若使用yarn：执行yarn patch troisjs，按照提示修改弹出的package.json文件添加"type": "module"，修改完成后执行yarn patch-commit -s 提示的临时补丁路径，补丁文件会自动存入项目.yarn/patches目录，Vercel安装依赖时自动应用。
• 若使用pnpm：在package.json中添加pnpm.patchedDependencies字段配置对应补丁即可。

调试时可以先在本地执行yarn build + yarn preview验证构建产物正常，再推送代码到Vercel部署。

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