# @ducklings/workers 中文文档

规范地址：https://npmcn.com/package/%40ducklings/workers/

版本：2\.0\.0
npm 元数据更新时间：2026-10-25T10:06:43.702Z
中文译文更新时间：2026-11-12T23:43:01.223Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40ducklings/workers
原文对照：https://npmcn.com/package/%40ducklings/workers/?lang=original
项目主页：https://github.com/tobilg/ducklings#readme
源码仓库：https://github.com/tobilg/ducklings

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

- 包体积（解压后）：53.3 MB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.0\.0
- 运行依赖：1 个
- peer 依赖：vite ^5\.0\.0 \|\| ^6\.0\.0 \|\| ^7\.0\.0
- 首次发布：2026-01-13T23:25:49.950Z
- 最新版本发布：2026-10-25T10:06:43.282Z
- 近 30 天下载量：24068（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

DuckDB WASM 用于使用 httpfs 和 Parquet 的 Cloudflare 工人

## 安装

```sh
npm install @ducklings/workers
```

也可以使用：`pnpm add @ducklings/workers`、`yarn add @ducklings/workers`、`bun add @ducklings/workers`

## README

# @ducklings/ 工人( )

DuckDB WASM 仅供云花板工人使用 `httpfs` 财务报告和审定财务报表 `parquet` 静态捆绑。 Async API 拥有完整的 TypeScript 支持.

> 云纹允许 [64 MiB 未按免费和有偿计划对每个工人进行压缩](https://developers.cloudflare.com/workers/platform/limits/#worker-size),没有压缩大小限制。 运行 `wrangler deploy --dry-run --outdir bundled` 和你的工人核对 `Total Upload`。选择基于CPU和其他运行时间要求的计划.
> 
> **延期说明:** 发表 `@ducklings/workers` 软件包不捆绑 DuckDB 的 `json` 在Cloudflare的部署规模预算范围内。 JSON 职能 `::JSON` 类型别名,和 `read_json()` 因此,标准包中没有。 发表 `@ducklings/browser` 软件包由于同样的原因省略了相同的扩展.
> 
> 用来建造以鸭湖为重点的工人 [`@ducklings/workers-ducklake`](https://www.npmjs.com/package/@ducklings/workers-ducklake)。 。 。 .

对于 Avro 或 Iceberg 查询, 使用 [`@ducklings/workers-iceberg`](https://www.npmjs.com/package/@ducklings/workers-iceberg),它增加了 httpfs 和 Parquet 的扩展。 从1.5.6起,这些应用程序还必须切换 `/wasm` 财务报告和审定财务报表 `/vite-plugin` 进口到那个包裹.

## 安装

```bash
npm install @ducklings/workers
```

## 快速启动

```typescript
import { init, DuckDB } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

export default {
  async fetch(request: Request): Promise<Response> {
    // Initialize with pre-compiled WASM module
    await init({ wasmModule });

    const db = new DuckDB();
    const conn = db.connect();

    // All queries are async
    const rows = await conn.query<{answer: number}>('SELECT 42 as answer');

    conn.close();
    db.close();

    return Response.json(rows);
  }
};
```

## Singleton 初始化(建议)

用于生产、重新使用数据库以及各种请求之间的连接,以避免重新启动间接费用:

```typescript
import { init, DuckDB, type Connection } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

// Global state (reused across requests in the same Worker instance)
let db: DuckDB | null = null;
let conn: Connection | null = null;
let initialized = false;

async function ensureInitialized(): Promise<void> {
  if (initialized && db && conn) {
    return;
  }

  await init({ wasmModule });
  db = new DuckDB();
  conn = db.connect();
  initialized = true;
}

export default {
  async fetch(request: Request): Promise<Response> {
    await ensureInitialized();

    const rows = await conn!.query('SELECT 42 as answer');
    return Response.json(rows);
  }
};
```

## 虚拟插件

用于使用 Vite 的项目 `@cloudflare/vite-plugin` 要构建 Cloudflare Workers, 我们提供一个处理 WASM 文件解析和复制的插件 :

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { cloudflare } from '@cloudflare/vite-plugin';
import { ducklingsWorkerPlugin } from '@ducklings/workers/vite-plugin';

export default defineConfig({
  plugins: [
    ducklingsWorkerPlugin(),
    cloudflare(),
  ],
});
```

### 插件选项

```typescript
ducklingsWorkerPlugin({
  // Name of the WASM file in the output directory (default: 'duckdb-workers.wasm')
  wasmFileName: 'duckdb-workers.wasm',
})
```

插件 :

-   决定: `@ducklings/workers/wasm` 导入到 wrangler 的相对路径
-   自动将 WASM 文件复制到正确的输出目录( 使用 Cloudflare vite 插件的嵌入式输出结构的工作)

## 特征

-   Async API - 所有查询方法返回承诺
-   Base WASM 有同化; 省略 Avro 和 Iceberg
-   内建的 Parquet 和 httpfs 扩展
-   完整 httpfs 支持通过 async `fetch()`
-   通过 Flechette (query + 插入) 箭头表格支持
-   编写带有类型安全参数的约束的声明
-   交易支持

## 为什么是单独包?

Cloudflare Workers不支持同步的XMLHttprequest(只使用浏览器的API). 此软件包使用 Emscripten 的 Asyncify 以启用 Async `fetch()` 调用,使 httpfs 正常工作以装入远程 Parquet 和 CSV 文件,加上 httpfs 写入路径 .

已发布的浏览器和工人软件包不捆绑 `json` 扩展名。 远程Parquet和CSV访问工作在标准包中. 通过远程 JSON 查询 `read_json()` 别.

| 软件包 | API 样式 | 大小( gzip) | 网页 |
| --- | --- | --- | --- |
| `@ducklings/browser` | Async (网络工人) | ~7.1 米贝 | XMLHttp 请求 |
| `@ducklings/workers` | 同步( 同步) | ~ 12.3 米贝 | 通过聚合获取( ) |

## API 密码

### 初始化

```typescript
import { init, version } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

// Initialize with pre-compiled WASM
await init({ wasmModule });

// Get DuckDB version
console.log(version()); // "v1.4.3"
```

### 查询方法( Async)

```typescript
const conn = db.connect();

// Returns array of objects
const rows = await conn.query<{id: number, name: string}>('SELECT * FROM users');

// Returns Arrow Table (Flechette)
const table = await conn.queryArrow('SELECT * FROM users');

// Execute without returning results
await conn.execute('INSERT INTO users VALUES (1, "Alice")');

// Insert Arrow IPC data into a table
const ipc = tableToIPC(arrowTable, { format: 'stream' });
await conn.insertArrowFromIPCStream('my_table', ipc);
```

### 发言稿

```typescript
const stmt = conn.prepare('SELECT * FROM users WHERE id = ? AND active = ?');
stmt.bindInt32(1, 42);
stmt.bindBoolean(2, true);
const results = await stmt.run();  // Note: async
stmt.close();
```

### 远程文件( httpfs)

```typescript
// Query remote Parquet file
const rows = await conn.query(`
  SELECT * FROM 'https://example.com/data.parquet'
  LIMIT 10
`);

// Query remote CSV
const csv = await conn.query(`
  SELECT * FROM read_csv('https://example.com/data.csv')
`);

```

`read_json()`,JSON功能,例如 `json_extract(...)`,则 `::JSON` 类型别名在标准工人包中不可用,因为 DuckDB `json` 扩展名没有捆绑。 标准浏览器包省略了相同的扩展.

### R2 密钥

使用 DuckDB 机密访问私有 S3 兼容存储 :

```typescript

// Cloudflare R2
await conn.execute(`
  CREATE SECRET my_r2 (
    TYPE R2,
    KEY_ID 'your-r2-access-key-id',
    SECRET 'your-r2-secret-access-key',
    ACCOUNT_ID 'your-cloudflare-account-id'
  )
`);
const r2Data = await conn.query(`SELECT * FROM 'r2://bucket/file.parquet'`);
```

**支持的秘密类型 :** `S3`, (中文(简体) ), `R2`, (中文(简体) ), `GCS`

对于Cloudflare工人,你可以使用 [工人秘密](https://developers.cloudflare.com/workers/configuration/secrets/) 安全存储证书。 见 [实例工作者](https://github.com/tobilg/ducklings/tree/main/packages/example-cloudflare-worker) (c) 全面执行《公约》.

### 箭头 IPC 端点

返回查询结果作为箭头 IPC 流以高效传输数据:

```typescript
import { init, DuckDB, tableToIPC } from '@ducklings/workers';
import wasmModule from '@ducklings/workers/wasm';

export default {
  async fetch(request: Request): Promise<Response> {
    await init({ wasmModule });

    const db = new DuckDB();
    const conn = db.connect();

    const table = await conn.queryArrow('SELECT * FROM range(1000) t(i)');
    const ipcBytes = tableToIPC(table, { format: 'stream' });

    conn.close();
    db.close();

    return new Response(ipcBytes, {
      headers: { 'Content-Type': 'application/vnd.apache.arrow.stream' },
    });
  }
};
```

### 交易

```typescript
// Manual control
await conn.beginTransaction();
try {
  await conn.query('INSERT INTO accounts VALUES (1, 1000)');
  await conn.commit();
} catch (e) {
  await conn.rollback();
  throw e;
}

// Or use the wrapper (auto-rollback on error)
await conn.transaction(async () => {
  await conn.query('INSERT INTO orders VALUES (...)');
  return 'success';
});
```

### 箭头支持

```typescript
import { tableFromArrays, tableFromIPC, tableToIPC, utf8 } from '@ducklings/workers';

// Query as Arrow Table
const table = await conn.queryArrow('SELECT * FROM users');

// Build Arrow tables
const custom = tableFromArrays({
  id: [1, 2, 3],
  name: ['Alice', 'Bob', 'Charlie']
});

// Serialize/deserialize Arrow IPC
const bytes = tableToIPC(table, { format: 'stream' });
const restored = tableFromIPC(bytes);

// Insert Arrow IPC data directly into a table
const data = tableFromArrays(
  { id: [1, 2], label: ['x', 'y'] },
  { types: { label: utf8() } }  // Use plain utf8 (see note below)
);
const ipc = tableToIPC(data, { format: 'stream' });
await conn.insertArrowFromIPCStream('my_table', ipc);
```

> **词典编码 :** 弗莱歇特的 `tableFromArrays()` 默认为 `dictionary(utf8())` 用于字符串列。 内部使用的Arrow IPC解码器不支持词典编码流. 建表格时 `insertArrowFromIPCStream()`,明确设置字符串列为 `utf8()`数字 :
> 
> ```typescript
> import { utf8 } from '@ducklings/workers';
> tableFromArrays({ col: ['a', 'b'] }, { types: { col: utf8() } });
> ```

## 浏览器使用

对于浏览器环境, 使用 [`@ducklings/browser`](https://www.npmjs.com/package/@ducklings/browser) 而不是在网络工作员中运行查询.

## 限制

-   **没有动态扩展装入**:只有静态编译扩展可用. 默认工人建筑包括Parquet和httpfs. Avro, Iceberg, DuckLake, Space, 和JSON没有捆绑. `INSTALL`编号 :`LOAD` 用于其他扩展的命令不会工作.

## 许可证

麻省理工学院

## 常见问题

### @ducklings/workers 是什么？

DuckDB WASM 用于使用 httpfs 和 Parquet 的 Cloudflare 工人

### 如何安装 @ducklings/workers？

在项目目录运行 npm install @ducklings/workers，或使用 pnpm add / yarn add / bun add。

### @ducklings/workers 支持 TypeScript 吗？

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

### @ducklings/workers 支持 ESM 还是 CommonJS？

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

### @ducklings/workers 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @ducklings/workers 可以商用吗？

@ducklings/workers 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ducklings/workers 的下载量有多少？

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

### @ducklings/workers 还在维护吗？

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