# @electric-sql/client 中文文档

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

版本：1\.5\.28
npm 元数据更新时间：2026-09-09T11:29:57.830Z
中文译文更新时间：2026-11-13T10:59:42.675Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：2.4 MB，54 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- 首次发布：2024-08-07T21:39:04.112Z
- 最新版本发布：2026-09-09T11:29:57.495Z
- 近 30 天下载量：8352591（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：89（近 12 个月 39 个）

## 中文简介

到处都是邮箱 数据同步 随时需要.

## 安装

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

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

## README

[![ElectricSQL logo](https://raw.githubusercontent.com/electric-sql/meta/main/identity/ElectricSQL-logo-black.svg)](https://electric-sql.com/)

[![](https://github.com/electric-sql/electric/actions/workflows/ts_test.yml/badge.svg)](https://github.com/electric-sql/electric/actions) [![License - Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-green)](https://github.com/electric-sql/electric/blob/main/LICENSE) [![Status - Beta](https://img.shields.io/badge/status-beta-orange)](https://github.com/electric-sql/electric-n%20%20ext/milestones) [![Chat - Discord](https://img.shields.io/discord/933657521581858818?color=5969EA&label=discord)](https://discord.electric-sql.com/) [![](https://img.shields.io/twitter/follow/ElectricSQL.svg?style=social&label=Follow%20@ElectricSQL)](https://x.com/ElectricSQL)

# 电气SQL 的脚本客户端

现代应用的实时Postgres同步.

电气提供 [HTTP 接口](https://electric-sql.com/docs/api/http) 到 Postgres 使大量客户端能够查询并实时更新数据库子集,称为 [形状](https://electric-sql.com//docs/guides/shapes)通过这种方式,Electric将Postgres转换成实时数据库.

TypeScript客户端帮助从浏览器和其他JavaScript环境中的HTTP API读取形状,如边缘功能和服务器侧节点/Bun/Deno应用程序. 它支持精细和粗细的活性模式——你可以订阅看到每一个变化的行,或者只需订阅就可以在变化时获得整个形状. 客户端也通过基于函数的参数和头来支持动态选项,使其易于处理认证符,用户上下文等运行时值.

## 安装

客户在国家预防机制上公布为: [`@electric-sql/client`](https://www.npmjs.com/package/@electric-sql/client)数字 :

```sh
npm i @electric-sql/client
```

## 如何使用

客户输出 a `ShapeStream` 逐行更新到形状以及 `Shape` 用于获取整个形状的更新.

### `ShapeStream`

```tsx
import { ShapeStream } from '@electric-sql/client'

const BASE_URL = 'http://localhost:3000'

// Passes subscribers rows as they're inserted, updated, or deleted
const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: {
    table: `foo`,
  },
})

// You can also add custom headers and URL parameters
const streamWithParams = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  headers: {
    Authorization: 'Bearer token',
  },
  params: {
    table: `foo`,
    'custom-param': 'value',
  },
})

stream.subscribe((messages) => {
  // messages is an array with one or more row updates
  // and the stream will wait for all subscribers to process them
  // before proceeding
})
```

### `Shape`

```tsx
import { ShapeStream, Shape } from '@electric-sql/client'

const BASE_URL = 'http://localhost:3000'

const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: {
    table: `foo`,
  },
})
const shape = new Shape(stream)

// Returns promise that resolves with the latest shape data once it's fully loaded
await shape.rows

// passes subscribers shape data when the shape updates
shape.subscribe(({ rows }) => {
  // rows is an array of the latest value of each row in a shape.
})
```

### 反应原生/ Expo 应用程序生命周期

大都会和博览会解决软件包 `react-native` 用于本地建筑的导出, 因此标准导入自动电线 React Introduction `AppState` 输入 `ShapeStream`。如果您的捆绑器设置不能解决根 `react-native` 条件,使用明示 `@electric-sql/client/react-native` 入境点或通过 `runtimeVisibility` 当然 见 [类型脚本客户端 Docs](https://electric-sql.com/docs/sync/api/clients/typescript#react-native-and-expo-lifecycle-handling) 详细情况.

### 处理错误

ShepeStream 以自动重试支持提供强大的错误处理:

#### 1\. 有重试控制的流层错误处理器

这个 `onError` 处理器给予您对错误回收的全部控制 :

```typescript
import { ShapeStream, FetchError } from '@electric-sql/client'

const BASE_URL = 'http://localhost:3000'
const getRefreshedToken = () => 'refreshed-token'
const fallbackUserId = 'fallback-user-id'

const stream = new ShapeStream({
  url: `${BASE_URL}/v1/shape`,
  params: { table: `foo` },
  onError: (error) => {
    console.error('Stream error:', error)

    // IMPORTANT: Return an object to keep syncing!
    // Return void/undefined to stop syncing permanently.

    // Note: 5xx errors and network errors are automatically retried,
    // so onError is mainly for handling client errors (4xx)

    if (error instanceof FetchError) {
      if (error.status === 401) {
        // Unauthorized - refresh token and retry
        const newToken = getRefreshedToken()
        return {
          headers: {
            Authorization: `Bearer ${newToken}`,
          },
        }
      }

      if (error.status === 403) {
        // Forbidden - maybe change user context
        return {
          params: {
            table: `foo`,
            where: `user_id = $1`,
            params: [fallbackUserId],
          },
        }
      }
    }

    // Stop syncing for other errors (return void)
  },
})
```

**关键**编号: `onError` 调用返回值控制同步是否继续 :

-   **返回对象** (甚至为空) `{}`重试同步 :
    -   `{}` - 使用相同的参数和标题重试
    -   `{ params }` - 使用经修改的参数重试
    -   `{ headers }` - 用修改后的标题重试
    -   `{ params, headers }` - 用两个修改过的重试
-   **返回为空/ 未定义** 以永久停止溪流

处理器支持同步操作 :

```typescript
import { FetchError } from '@electric-sql/client'

const refreshAuthToken = async () => 'refreshed-token'

const options = {
  onError: async (error: Error) => {
    if (error instanceof FetchError && error.status === 401) {
      // Perform async token refresh
      const newToken = await refreshAuthToken()
      return {
        headers: { Authorization: `Bearer ${newToken}` },
      }
    }

    return {} // Retry other errors
  },
}
```

**自动重试**:客户端自动重试5xx服务器出错,网络出错,以及429个速率限制并有指数回放. 这个 `onError` 只有在这些重试被用尽后,或者对于像4xx客户端错误这样的不可重复的错误才引用回调.

**无 `onError`**: 如果没有 `onError` 提供了处理器,将抛出不可重复的错误(如4xx客户端错误)并停止流.

#### 2\. 订阅级错误回调

个人订阅者可以处理其订阅时特有的错误:

```typescript
stream.subscribe(
  (messages) => {
    // Handle messages
  },
  (error) => {
    // Handle errors for this specific subscription
    console.error('Subscription error:', error)
  }
)
```

注意: 订阅错误召回无法控制重试行为 - 使用流级 `onError` 对于这个.

#### 常见错误类型

设置错误 :

-   `MissingShapeUrlError`: 缺少所需的 URL 参数
-   `InvalidSignalError`无效的中止实例
-   `ReservedParamError`: 使用保留参数名称

运行时间出错 :

-   `FetchError`: HTTP 在取形状时出错(包括 `status`, (中文(简体) ), `url`, (中文(简体) ), `headers`(中文(简体) )
-   `FetchBackoffAbortError`: 使用中止符号获取中止
-   `MissingShapeHandleError`: 缺少所需的形状手柄
-   `ParserNullValueError`: NULL 值在不可变列中

见 [类型脚本客户端 Docs](https://electric-sql.com/docs/api/clients/typescript#error-handling) 更多细节.

总而言之,看看 [文件网站](https://electric-sql.com/) 财务报告和审定财务报表 [实例](https://electric-sql.com/demos) 更多信息.

## 开发

在 repo 根上安装 pnpm 工作空间 :

```shell
pnpm install
```

构建软件包 :

```shell
cd packages/typescript-client
pnpm build
```

## 测试

在一个终端中,启动后端运行:

```shell
cd ../sync-service
mix deps.get
mix stop_dev && mix compile && mix start_dev && iex -S mix
```

在此文件夹中:

```shell
pnpm test
```

## 常见问题

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

到处都是邮箱 数据同步 随时需要\.

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

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

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

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

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

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

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

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

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

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

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

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