Nuxt SSR项目集成@tui-nuxt/editor编辑器不显示且报错如何解决

排查修复步骤 #

• 校验SSR适配配置
  编辑器依赖浏览器DOM API，服务端渲染阶段不存在window、document对象，未做SSR适配会直接触发初始化报错。
  Nuxt2环境：在nuxt.config.js的build.transpile配置项中加入@tui-nuxt/editor，使用编辑器时用<client-only>标签包裹组件。
  Nuxt3环境：将编辑器封装为后缀带.client.vue的客户端组件，或直接在使用位置外层套<ClientOnly>标签。
• 校验依赖版本匹配
  @tui-nuxt/editor对Nuxt2、Nuxt3有不同的适配版本，跨版本安装会触发兼容错误。执行npm ls @tui-nuxt/editor nuxt查看版本匹配关系，版本不兼容时卸载当前包后安装对应适配版本即可。
• 校验样式引入完整性
  编辑器运行依赖自带样式文件，未引入会导致渲染异常。需要在全局样式或编辑器组件内引入基础样式：import '@toast-ui/editor/dist/toastui-editor.css'；如果使用了代码高亮、markdown扩展等插件，需要同步引入插件对应的样式文件。
• 校验初始化执行时机
  不要在服务端生命周期（如Nuxt2的asyncData、fetch，Nuxt3的useAsyncData服务端执行阶段）调用编辑器实例方法，所有编辑器初始化、实例操作都要放在客户端生命周期中执行，比如Nuxt2的mounted钩子、Nuxt3的onMounted钩子。
• 清除缓存重试
  所有配置修改后，先删除.nuxt、node_modules/.cache目录，再执行构建或启动命令，避免旧缓存导致配置不生效。

最小化验证示例 #

你可以通过以下测试组件确认配置是否生效：

<!-- Nuxt3 示例，Nuxt2可对应调整语法适配 -->
<template>
  <ClientOnly>
    <TuiEditor v-model="content" />
    <template #fallback>
      编辑器加载中
    </template>
  </ClientOnly>
</template>

<script setup>
import { ref } from 'vue'
const content = ref('测试文本')
</script>

<style scoped>
@import '@toast-ui/editor/dist/toastui-editor.css';
</style>

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