Nuxt 3 + TipTap执行nuxt generate报错：StarterKit.configure不是函数

问题概述 #

使用 Nuxt 3.0.0 + TipTap 2.0.0-beta.209 创建项目时，nuxt dev 和 SPA 模式运行正常，但执行 nuxt generate 命令会抛出 StarterKit.configure is not a function 错误，错误指向 pages/index.vue 中的编辑器配置代码。

报错信息 #

ERROR StarterKit.configure is not a function

at setup (/D:/dev/nuxt-tiptap-issue/.nuxt/prerender/chunks/index.ac796611.mjs:56:20)
at _sfc_main.setup (/D:/dev/nuxt-tiptap-issue/.nuxt/prerender/chunks/index.ac796611.mjs:321:23)
at callWithErrorHandling (node_modules@vue\runtime-core\dist\runtime-core.cjs.prod.js:15:22)
at setupStatefulComponent (node_modules@vue\runtime-core\dist\runtime-core.cjs.prod.js:5762:29)
at setupComponent (node_modules@vue\runtime-core\dist\runtime-core.cjs.prod.js:5743:11)
at renderComponentVNode (node_modules@vue\server-renderer\dist\server-renderer.cjs.prod.js:169:17)
at renderVNode (node_modules@vue\server-renderer\dist\server-renderer.cjs.prod.js:296:22)
at renderComponentSubTree (node_modules@vue\server-renderer\dist\server-renderer.cjs.prod.js:260:13)
at renderComponentVNode (node_modules@vue\server-renderer\dist\server-renderer.cjs.prod.js:185:16)
at renderVNode (node_modules@vue\server-renderer\dist\server-renderer.cjs.prod.js:296:22)

出错代码片段 #

const editor = useEditor({
  extensions: [
    CustomDocument,
    StarterKit.configure({
      document: false,
      heading: {
        levels: [1, 2, 3, 4, 5, 6],
      }
    }),
    // ...其他扩展
  ]
})

已尝试操作 #

执行 nuxt generate 时出现以下警告：

WARN Using experimental payload extraction for full-static output. You can opt-out by setting experimental.payloadExtraction to false.

已尝试将 experimental.payloadExtraction 设置为 false，但问题未解决。怀疑 StarterKit 导入异常，但无法定位修复。

解决方案 #

1. 将编辑器标记为客户端仅渲染 #

TipTap 是前端交互组件，服务端渲染时无需初始化编辑器。可以用 Nuxt 的 <ClientOnly> 组件包裹编辑器：

<template>
  <ClientOnly>
    <!-- 你的 TipTap 编辑器组件 -->
  </ClientOnly>
</template>

或在代码中仅在客户端初始化编辑器：

const editor = process.client ? useEditor({
  extensions: [
    CustomDocument,
    StarterKit.configure({
      document: false,
      heading: { levels: [1,2,3,4,5,6] }
    })
  ]
}) : null

2. 配置 Nuxt 打包时转译 TipTap 依赖 #

在 nuxt.config.ts 中添加 TipTap 相关包到 build.transpile，确保服务端打包时正确处理 ES 模块：

export default defineNuxtConfig({
  build: {
    transpile: ['@tiptap/core', '@tiptap/starter-kit', '@tiptap/vue-3']
  }
})

3. 降级 TipTap 版本 #

当前使用的 TipTap 为 beta 版本，可能存在兼容性问题。尝试降级到更稳定的 beta 版本（如 2.0.0-beta.200），重新安装依赖后执行 nuxt generate。

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