Tiptap与NextJS 14 Server Actions的JSON序列化兼容性问题解析

问题背景

在使用Tiptap富文本编辑器与NextJS 14的Server Actions功能集成时，开发者遇到了一个常见的JSON序列化问题。当尝试将包含heading节点的编辑器内容通过Server Actions传递到后端时，系统抛出错误："Only plain objects, and a few built-ins, can be passed to Server Actions. Classes or null prototypes are not supported"。

技术原理分析

这个问题的本质在于NextJS 14的Server Actions对传输数据的严格限制。Server Actions要求传递的数据必须是纯JavaScript对象(plain objects)，不能包含类实例或具有null原型的对象。

Tiptap编辑器底层使用ProseMirror作为核心引擎，当直接使用editor.state获取状态时，返回的是ProseMirror的文档状态对象，这个对象包含了一些特殊的类实例和原型方法，无法被NextJS的Server Actions直接序列化。

解决方案对比

推荐方案：使用getJSON方法

Tiptap专门提供了editor.getJSON()方法来获取纯JSON格式的编辑器内容。这个方法会返回一个完全符合JSON标准的对象结构，可以被NextJS Server Actions正确处理。

const content = editor.getJSON();
// 这个content可以直接传递给Server Actions

替代方案：手动序列化

如果由于某些原因必须使用editor.state，可以采用手动序列化的方式：

const content = JSON.parse(JSON.stringify(editor.state));
// 双重转换确保获得纯JSON对象

不过这种方法效率较低，且不是官方推荐的做法。

最佳实践建议

1. 始终优先使用getJSON：这是Tiptap专门为获取可序列化内容设计的方法
2. 避免直接使用state对象：除非确实需要访问底层ProseMirror状态
3. 数据验证：在Server Actions中仍然需要对接收的JSON数据进行验证
4. 错误处理：添加适当的错误处理逻辑，捕获可能的序列化异常

深入理解

Tiptap的文档模型是基于ProseMirror构建的，而ProseMirror内部使用了一种高效的、不可变的数据结构来表示文档状态。这种设计在编辑器操作时非常高效，但不适合直接用于网络传输。getJSON()方法实际上执行了一个转换过程，将ProseMirror的内部表示转换为标准的JSON树结构。

对于heading节点这类包含额外属性(如level)的元素，getJSON()会将其转换为标准的对象表示，例如：

{
  "type": "heading",
  "attrs": {
    "level": 2
  },
  "content": [...]
}

这种格式完全符合JSON规范，可以被任何现代JavaScript环境正确处理。

总结

在将Tiptap编辑器内容传递到NextJS Server Actions时，开发者应当使用editor.getJSON()方法获取可序列化的JSON数据，而不是直接使用editor.state。这种做法不仅解决了兼容性问题，也是Tiptap官方推荐的数据获取方式。理解编辑器内部状态与可传输数据之间的区别，有助于开发者构建更健壮的富文本编辑应用。