# 协同编辑

**Repository Path**: hongjiazhun/collaborative-editing

## Basic Information

- **Project Name**: 协同编辑
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-29
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 编辑器协同（Vue 3 + Tiptap + Y.js + WebRTC）

一套基于 **Vue 3 + Tiptap** 富文本编辑器、**Y.js** 协同框架、**WebRTC**（自建信令服务器）的实时协同编辑示例。

## 目录结构

```
编辑器协同/
├── server/                     # 信令服务器（后端）
│   ├── package.json
│   └── signaling-server.js     # WebRTC 信令服务器
└── client/                     # 前端编辑器（前端）
    ├── package.json
    ├── vite.config.js
    ├── index.html
    └── src/
        ├── main.js
        ├── App.vue             # 应用入口 + 房间切换
        ├── style.css
        ├── components/
        │   └── TiptapEditor.vue # 协同富文本编辑器组件
        └── collab/
            ├── SignalingClient.js  # WebRTC 信令客户端
            └── WebRtcProvider.js   # Y.js WebRTC Provider
```

## 技术栈

| 模块 | 技术 | 作用 |
| --- | --- | --- |
| 编辑器 | Tiptap (基于 ProseMirror) | 富文本编辑能力 |
| 协同框架 | Y.js | 文档状态同步与冲突解决（CRDT） |
| 编辑器协同绑定 | @tiptap/extension-collaboration / y-prosemirror | 把 Y.Doc 绑定到 ProseMirror |
| 传输层 | WebRTC (DataChannel) | peer 间低延迟数据通道 |
| 信令 | WebSocket (自建 Node 服务器) | 协助 WebRTC 建立连接 |

## 协同原理

1. 每个客户端持有一个 `Y.Doc`，文档正文存储在 `Y.XmlFragment('prosemirror')`。
2. `y-prosemirror`（通过 Tiptap 的 `Collaboration` 扩展）把 `Y.Doc` 与 ProseMirror 视图双向绑定：
   - 本地编辑 → ProseMirror 事务 → 写入 `Y.Doc`。
   - 远端 `Y.Doc` 更新 → ProseMirror 视图刷新。
3. `WebRtcProvider` 监听 `Y.Doc` 的 `update` 事件，把更新编码为二进制帧，通过 WebRTC DataChannel 广播给所有 peer。
4. 收到 peer 的二进制帧后，按 `y-protocols/sync` 协议应用到本地 `Y.Doc`。
5. Y.js 基于 CRDT，自动合并并发编辑，无需中心服务器解决冲突。

## 启动方式

> 前端和后端分属不同文件夹，需要**分别安装依赖、分别启动**。

### 1. 启动信令服务器（后端）

```bash
cd server
npm install
npm start
# 默认监听 ws://localhost:4444
```

### 2. 启动前端编辑器（前端）

```bash
cd client
npm install
npm run dev
# 默认监听 http://localhost:5173
```

### 3. 体验协同

- 浏览器打开 `http://localhost:5173`。
- **再开一个标签页**（或不同浏览器 / 不同设备）打开同一地址，确保房间名相同。
- 在任一标签页编辑，另一个标签页会实时同步。

## 配置说明

- **信令服务器端口**：通过环境变量 `PORT` 修改，例如 `PORT=5000 node signaling-server.js`。
- **前端连接的信令地址**：在 `client/src/App.vue` 中修改 `signalingUrl`。
- **房间名**：在前端页面顶部输入框中切换，同一房间名 = 同一协同文档。

## 说明

本示例的 `WebRtcProvider` 是一个**简化版**的 y-webrtc 实现，目的是清晰展示协同同步原理（信令交换 + DataChannel + Y.js sync 协议）。生产环境如需更完整的能力（awareness 光标、断线重连、房间密码等），可直接替换为官方 `y-webrtc` 包。