# @electric-sql/y-electric 中文文档

规范地址：https://npmcn.com/package/%40electric-sql/y-electric/

版本：0\.1\.54
npm 元数据更新时间：2026-09-09T11:31:23.274Z
中文译文更新时间：2026-11-14T02:18:26.126Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40electric-sql/y-electric
原文对照：https://npmcn.com/package/%40electric-sql/y-electric/?lang=original
项目主页：https://electric-sql.com/
源码仓库：https://github.com/electric-sql/electric

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：216 kB，20 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2025-05-12T19:37:57.827Z
- 最新版本发布：2026-09-09T11:31:22.596Z
- 近 30 天下载量：2527（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：55（近 12 个月 38 个）

## 中文简介

电气SQL的YJS网络供应商

## 安装

```sh
npm install @electric-sql/y-electric
```

也可以使用：`pnpm add @electric-sql/y-electric`、`yarn add @electric-sql/y-electric`、`bun add @electric-sql/y-electric`

## README

# Y 电子

A 类 [对](https://yjs.dev/) [提供者](https://docs.yjs.dev/ecosystem/connection-provider) 可以使用YJS、ElectricSQL和Postgres进行实时协作文档编辑。 它支持 [意识](https://docs.yjs.dev/getting-started/adding-awareness) 并可用于任意 Yjs [数据库](https://docs.yjs.dev/ecosystem/database-provider) 供养者. 见一个完整的例子 [这里](https://github.com/electric-sql/electric/tree/main/examples/yjs)。 。 。 .

## 如何运作

使用Yjs和Electric同步共享文档的典型流程如下:

1.  开发者将显示形状代理 [授权](https://electric-sql.com/docs/guides/auth) 形状请求
2.  客户定义 a [形状](https://electric-sql.com/docs/guides/shapes) 用于同步更改 a [Y. 医生](https://docs.yjs.dev/api/y.doc)
3.  开发者会曝光用于处理 Yjs 更新的 \[写 API\] (# 手写)
4.  来啊! Y- Electric 自动在所有连接客户端共享更新

### 关键特性

### 基本设置

```typescript
import * as Y from 'yjs'
import {
  ElectricProvider,
  LocalStorageResumeStateProvider,
} from '@electric-sql/y-electric'
import { Awareness } from 'y-protocols/awareness'
import { parseToDecoder } from '@electric-sql/y-electric/utils'

const ydoc = new Y.Doc()
const awareness = new Awareness(ydoc)
const resumeStateProvider = new LocalStorageResumeStateProvider('my-doc')

const provider = new ElectricProvider({
  doc: ydoc,
  documentUpdates: {
    shape: {
      url: SHAPE_PROXY_URL,
      params: {
        table: `ydoc_update`,
        where: `room = '${room}'`,
      },
      parser: parseToDecoder,
    },
    sendUrl: DOC_UPDATES_SEND_URL,
    getUpdateFromRow: (row) => row.op,
  },
  awarenessUpdates: {
    shape: {
      url: SHAPE_PROXY_URL,
      params: {
        table: `ydoc_awareness`,
        where: `room = '${room}'`,
      },
      parser: parseToDecoder,
    },
    sendUrl: AWARENESS_UPDATES_SEND_URL,
    protocol: awareness,
    getUpdateFromRow: (row) => row.op,
  },
  resumeState: resumeStateProvider.load(),
})

// Subscribe to resume state changes to persist them
resumeStateProvider.subscribeToResumeState(provider)
```

### 处理写入

ElectricSQL是一个读取路径同步引擎. 这意味着您会带回您自己的 API 来处理文件和认知更新 。 查看我们的服务器样本执行 [这里](https://github.com/electric-sql/electric/blob/main/examples/yjs/server/server.ts)很简单!

#### 文件更新

Y-Electric 发送 YJS 文档作为二进制数据更新. 您可以直接将请求的正文保存为字节列入数据库.

```sql
-- Schema definition
CREATE TABLE ydoc_updates(
    id uuid DEFAULT uuid_generate_v4() PRIMARY KEY,
    room text NOT NULL,
    op bytea NOT NULL
)
-- Save updates into individual rows
INSERT INTO ydoc_updates (room, op) VALUES ($1, $2)`
```

#### 最新认识

意识协议执行为每个cliendId单独行保存向量时钟:

以下是ydoc 认知的示例性计划定义:

```sql
-- Schema definitions
CREATE TABLE ydoc_awareness(
  client_id TEXT,
  room TEXT,
  op BYTEA NOT NULL,
  updated TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (client_id, room)
);
-- Save
INSERT INTO ydoc_awareness (room, client_id, op, updated) VALUES ($1, $2, $3, now())
         ON CONFLICT (client_id, room) DO UPDATE SET op = $3, updated = now()
```

建议您可以使用数据库触发器来收集旧客户行, 因为提供者无法在客户端消失时进行可靠性检测:

```sql
CREATE OR REPLACE FUNCTION gc_awareness_timeouts()
RETURNS TRIGGER AS $$
BEGIN
    DELETE FROM ydoc_awareness
    WHERE updated < (CURRENT_TIMESTAMP - INTERVAL '30 seconds') AND room = NEW.room;
    RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER gc_awareness_timeouts_trigger
AFTER INSERT OR UPDATE ON ydoc_awareness
FOR EACH ROW
EXECUTE FUNCTION gc_awareness_timeouts();
```

### 客户端中的 Schema 映射

在客户端,你需要通过一个 `getUpdateFromRow` 用更新二进制提取列。 这使得Y-Electric能够与任何后端的策略合作.

### 储存供应商

Y-电动工程与现有 [数据库提供者](https://docs.yjs.dev/ecosystem/database-provider) 以本地存储文档。 在本地保存文档时,我们建议提供 `ElectricResumeStateProvider` 以保存文档的恢复点,否则整个文档将在新的客户端会话开始后重新发送.

## 常见问题

### @electric-sql/y-electric 是什么？

电气SQL的YJS网络供应商

### 如何安装 @electric-sql/y-electric？

在项目目录运行 npm install @electric-sql/y-electric，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 intent，可以用 npx intent 直接运行。

### @electric-sql/y-electric 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @electric-sql/y-electric 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @electric-sql/y-electric 可以商用吗？

@electric-sql/y-electric 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @electric-sql/y-electric 的下载量有多少？

根据 npm 官方下载统计，@electric-sql/y-electric 在 2026/10/14 – 2026/11/12 这 30 天内被下载 2,527 次，日均约 84 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @electric-sql/y-electric 还在维护吗？

最新版本 0\.1\.54 发布于 2026/09/09（2 个月前）；至今共发布 55 个版本，其中过去 12 个月发布了 38 个；首次发布于 2025/05/13。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。