# Tiptap + Yjs WebSocket

**Repository Path**: yertqyang/tiptap---yjs-web-socket

## Basic Information

- **Project Name**: Tiptap + Yjs WebSocket
- **Description**: Tiptap + Yjs WebSocket这是一个基于 Vue 3 + Vite 构建的实时富文本协同编辑 Demo。使用了 [Tiptap](https://tiptap.
dev/) 编辑器和 [Yjs](https://github.com/yjs/yjs) CRDT 算法库，通过 WebSocket 实现多用
户实时同步。

- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-12-31
- **Last Updated**: 2026-01-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Tiptap + Yjs WebSocket 协同编辑示例

这是一个基于 Vue 3 + Vite 构建的实时富文本协同编辑 Demo。使用了 [Tiptap](https://tiptap.dev/) 编辑器和 [Yjs](https://github.com/yjs/yjs) CRDT 算法库，通过 WebSocket 实现多用户实时同步。

## ✨ 功能特性

- **实时协同编辑**：多个用户可以同时编辑同一个文档，内容实时同步。
- **光标感知**：可以看到其他在线用户的光标位置和名字。
- **用户状态**：随机生成用户名和颜色，展示当前在线用户数量。
- **基础富文本**：支持加粗、斜体、删除线、代码块、标题、列表等基础格式。
- **离线支持**：基于 Yjs 的 CRDT 算法，能够处理网络延迟和冲突。

## 🛠️ 技术栈

- **前端框架**：[Vue 3](https://vuejs.org/)
- **构建工具**：[Vite](https://vitejs.dev/)
- **编辑器**：[Tiptap v2](https://tiptap.dev/)
- **协同算法**：[Yjs](https://github.com/yjs/yjs)
- **通信协议**：WebSocket (`y-websocket`)

## 🚀 快速开始

### 1. 安装依赖

```bash
npm install
```

### 2. 启动服务

你需要同时启动 WebSocket 协同服务和前端开发服务器。

**终端 1：启动 WebSocket 服务**

```bash
npm run server
```

_服务将在 `ws://localhost:1234` 启动_

**终端 2：启动前端应用**

```bash
npm run dev
```

_访问 `http://localhost:5173`_

### 3. 验证协同功能

1. 打开浏览器访问 `http://localhost:5173`。
2. 打开另一个浏览器窗口（或隐身模式）访问同一地址。
3. 在任意窗口输入内容，你会看到内容实时同步，并且能看到对方的光标。

## � 打包与生产环境部署

### 1. 构建生产环境代码

```bash
npm run build
```

构建完成后，静态资源将生成在 `dist` 目录下。

### 2. 本地预览生产构建

```bash
npm run preview
```

此命令会启动一个本地服务器来预览 `dist` 目录的内容，通常运行在 `http://localhost:4173`。

### ⚠️ 重要提示

**前端构建（`npm run build`）只包含界面代码，不包含协同服务。**

在生产环境中，你依然需要独立运行 WebSocket 服务：

1.  **启动 WebSocket 服务**：保持 `npm run server` 运行（或使用 PM2 等工具后台运行）。
2.  **部署前端**：将 `dist` 目录部署到 Nginx、Vercel 或其他静态托管服务。
3.  **修改连接地址**：如果 WebSocket 服务和前端不在同一域名/端口，记得修改 `src/components/TiptapEditor.vue` 中的 WebSocket 连接地址：

    ```typescript
    const provider = new WebsocketProvider(
    	'ws://your-production-server.com:1234', // 修改为实际的 WebSocket 服务地址
    	'tiptap-vue-collaboration',
    	ydoc
    )
    ```

## �📂 项目结构

```
.
├── public/
├── src/
│   ├── components/
│   │   └── TiptapEditor.vue  # 核心编辑器组件，包含协同逻辑
│   ├── App.vue               # 主应用入口
│   ├── main.ts
│   └── utils.ts              # 工具函数（生成随机用户等）
├── package.json              # 包含 server 启动脚本
└── vite.config.ts
```

## 📝 核心代码说明

协同编辑的核心配置在 `src/components/TiptapEditor.vue` 中：

```typescript
// 1. 创建 Yjs 文档实例
const ydoc = new Y.Doc()

// 2. 连接 WebSocket Provider
const provider = new WebsocketProvider(
	'ws://localhost:1234',
	'tiptap-vue-collaboration', // 房间名称
	ydoc
)

// 3. 配置 Tiptap 编辑器
const editor = useEditor({
	extensions: [
		// ... 其他扩展
		Collaboration.configure({
			document: ydoc // 绑定 Yjs 文档
		}),
		CollaborationCursor.configure({
			provider: provider,
			user: {
				name: getRandomName(),
				color: getRandomColor()
			}
		})
	]
})
```