Liveblocks 为您提供构建模块和基础设施，使您应用中的用户与 AI 能够协同工作。

立即免费开始

现成功能

Liveblocks 包含一系列协作构建模块，您可以单独使用或组合使用。这些现成的功能提供了预构建的组件、钩子和 API，能够处理实时协作的复杂性，让您专注于打造产品独特的用户体验。

• 评论 - 直接在您的产品中添加上下文相关的评论
• 多人游戏 - 为您的产品体验添加实时协作功能
• AI 助手 - 在您的产品中加入 AI 合作者
• 通知 - 为您的应用添加通知，以保持用户的活跃度

SDK 和软件包

针对特定库和框架的软件包，用于将 Liveblocks 驱动的协作体验集成到您的产品中。这些集成旨在满足各种协作用例，例如协作文本编辑器、评论、通知等。

• @liveblocks/client
• @liveblocks/react
• @liveblocks/react-ui
• @liveblocks/react-tiptap
• @liveblocks/react-blocknote
• @liveblocks/node-prosemirror
• @liveblocks/react-lexical
• @liveblocks/node-lexical
• @liveblocks/redux
• @liveblocks/zustand
• @liveblocks/yjs
• @liveblocks/node
• @liveblocks/emails
• @liveblocks/chat-sdk-adapter
• Python SDK
• REST API

开发者资源

• 文档 - /docs
• 指南 - /guides
• 教程 - /tutorial
• 示例 - /examples
• 变更日志

社区与支持

• GitHub 问题 用于报告您在使用 Liveblocks 时遇到的 bug 和错误。
• Discord 是参与 Liveblocks 社区、提问和分享技巧的好地方。
• 电子邮件 可直接联系我们获取支持和销售咨询。
• X 提供更新、公告、博客文章以及 Liveblocks 的实用技巧。

许可证

本仓库的大部分内容采用 Apache License 2.0 许可证，版权 © 2021 至今归 Liveblocks 所有。部分组件则采用 AGPL-3.0 或更高版本许可证。

详细信息请参阅 LICENSE。

Liveblocks 快速上手指南

Liveblocks 是一套用于在应用中构建实时协作体验的基础设施，支持多人编辑、评论、通知及 AI 代理等功能。本指南将帮助你快速集成 Liveblocks 到 React 项目中。

环境准备

• Node.js: 建议版本 18.0 或更高。
• 包管理器: npm, yarn, pnpm 或 bun。
• 前端框架: 本示例以 React 为主（Liveblocks 也支持 Vue、Svelte 等，但 React 生态集成最完善）。
• Liveblocks 账号: 访问 Liveblocks 官网 注册并获取 Public Key。

安装步骤

根据你的项目需求，安装核心客户端库和 React 绑定库。如果需要使用预制的 UI 组件（如评论框、光标显示），还需安装 @liveblocks/react-ui。

npm install @liveblocks/client @liveblocks/react @liveblocks/react-ui

如果你正在使用 Next.js 或其他需要服务端渲染的框架，可能还需要安装 Node 端 SDK：

npm install @liveblocks/node

基本使用

以下是一个最简单的实时状态同步示例（例如共享一个计数器或文本状态）。

1. 初始化 Liveblocks Client

在你的应用入口或专用配置文件中创建 client 实例。请将 "YOUR_PUBLIC_KEY" 替换为你从 Dashboard 获取的公钥。

// liveblocks.config.ts
import { createClient } from "@liveblocks/client";
import { createRoomContext } from "@liveblocks/react";

const client = createClient({
  publicApiKey: "YOUR_PUBLIC_KEY", // 替换为你的公钥
});

// 定义房间中存储的数据结构类型
type Presence = {
  cursor: { x: number; y: number } | null;
};

type Storage = {
  counter: number;
};

// 导出 hooks 和组件
export const {
  suspense: {
    RoomProvider,
    useMyPresence,
    useStorage,
    useMutation,
  },
} = createRoomContext<Presence, Storage>(client);

2. 在组件中使用

使用 RoomProvider 包裹你的应用部分，并使用 hooks 读取和更新状态。

// App.tsx
import { RoomProvider, useMyPresence, useStorage, useMutation } from "./liveblocks.config";

function CollaborativeApp() {
  // 读取共享存储中的 counter
  const counter = useStorage((root) => root.counter);

  // 更新共享状态的 mutation
  const incrementCounter = useMutation(({ storage }) => {
    const currentCounter = storage.get("counter");
    storage.set("counter", currentCounter + 1);
  }, []);

  // 更新当前用户的存在状态（例如鼠标位置）
  const [myPresence, updateMyPresence] = useMyPresence();

  return (
    <div>
      <h1>实时计数器: {counter}</h1>
      <button onClick={incrementCounter}>增加计数</button>
      
      <p>我的光标位置: {JSON.stringify(myPresence.cursor)}</p>
      <button 
        onMouseMove={(e) => {
          updateMyPresence({ cursor: { x: e.clientX, y: e.clientY } });
        }}
      >
        移动鼠标以更新位置
      </button>
    </div>
  );
}

export default function Page() {
  return (
    // roomId 必须是唯一的，用于标识协作会话
    <RoomProvider id="my-room-id" initialPresence={{ cursor: null }} initialStorage={{ counter: 0 }}>
      <CollaborativeApp />
    </RoomProvider>
  );
}

3. 运行项目

启动你的开发服务器：

npm run dev

打开多个浏览器窗口访问同一页面，你将看到计数器和鼠标位置的实时同步效果。

---

下一步建议：

• 查看 官方文档 了解更复杂的场景，如富文本协作（Tiptap/Lexical）、评论系统和通知功能。
• 参考 Examples 获取完整的项目模板。