# @bearly/flock 中文文档

规范地址：https://npmcn.com/package/%40bearly/flock/

版本：0\.2\.3
npm 元数据更新时间：2026-10-30T01:24:05.943Z
中文译文更新时间：2026-11-07T19:53:48.361Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bearly/flock
原文对照：https://npmcn.com/package/%40bearly/flock/?lang=original
项目主页：https://github.com/beorn/bearly/tree/main/packages/flock
源码仓库：https://github.com/beorn/bearly

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

- 包体积（解压后）：30.7 kB，10 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：1 个
- 首次发布：2026-08-09T17:46:45.634Z
- 最新版本发布：2026-10-30T01:24:05.576Z
- 近 30 天下载量：9169（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：5（近 12 个月 5 个）

## 中文简介

本地 macOS 和 Linux 文件系统中 Bun 的 crash- safe fd- hold 羊群所有权

## 安装

```sh
npm install @bearly/flock
```

也可以使用：`pnpm add @bearly/flock`、`yarn add @bearly/flock`、`bun add @bearly/flock`

## README

# @ carely/ flock (英语)

本地 macOS 和 Linux 上的 Bun 和 Node 24 的 crash- safe, fd- hold 咨询文件锁定 文件系统.

`@bearly/flock` 是一个小 `flock(2)` 有三项保证:

-   内核在最后描述符关闭后释放所有权,包括 当程序收到时 `SIGKILL`· ;
-   仅限 `EAGAIN` 编号 : `EWOULDBLOCK` (b) 其他系统调用 失败和错误;
-   可选的诊断字节是完全写入和fsynced 之前的 获取的手柄被还原 .

持久路径名及其字节是诊断,而不是所有. 文件为 释放后有意保留,并可描述前主人。 使用 `isFlockHeld()` 以观察目前的所有权.

## 安装

> 从 npm 安装 。 源安装需要 Bun 或 有 TypeScript 剥取的节点 24.

```bash
bun add @bearly/flock
```

Bun用自己的东西 `bun:ffi` 适配器;节点使用预建的克菲 3.3.2适配器. 运行时间都无法装入另一个绑定值 。 Koffi 安装脚本不可信; 在支持的预建平台上不需要编译器 .

| 运行时间和平台 | 证据 |
| --- | --- |
| Bun, Linux 和 macOS 软件 | 现有土著合同套房 |
| 节点 24, Linux x64 | 已计量的承接FD和空难释放合同套间 |
| 节点24、Linux arm64和macOS x64/arm64 | 上游预建;我们没有测量 |
| 窗口 | 不支持 |

MacOS上的节点需要同一个合同套房在消费者通过之前通过 声明支持。 这个 合同仅限于本地文件系统。 网络文件系统可以执行 `flock` 和不同的语义 并不属于这个包的保证.

## 使用量

```ts
import { tryAcquireFlock } from "@bearly/flock"

using lock = tryAcquireFlock("/tmp/my-app/writer.lock", {
  body: `${JSON.stringify({ pid: process.pid })}\n`,
})

if (lock === null) throw new Error("another writer owns the resource")
// The lock remains held until this scope closes its fd.
```

对于必须无限期地等待的同步关键部分:

```ts
import { acquireFlockBlocking } from "@bearly/flock"

using lock = acquireFlockBlocking("/tmp/my-app/migration.lock")
runMigration()
```

对于一个有限的同步等待, `acquireFlockWithTimeout(path, timeoutMs, options?)` 返回控点或 `null` 当约束到期时。 它使用一个描述符和 单调时间, 停止整个呼叫线 在尝试之间。 打电话的人 选择绑定;取消、路径政策和错误措辞保持不变. 现有 `tryAcquireFlock()` 仍然不等待就立即尝试.

## 描述式继承

`lock.fd` 是公开的,这样主管就可以将获得的描述符传递给 孩子们. `release()` 只关闭此手柄的描述符; 它从不调用 `LOCK_UN`,因为明确解锁也会释放一个仍然拥有的锁 通过继承的复制。 内核在上次后放弃所有权 打开文件描述的描述结束 .

`lock.held` 只报告此本地控件。 之后就变假了 `lock.release()` 即使继承的孩子仍然拥有一个复制品.

## 诊断字节

`lock.replaceBody(body)` 切换出, 写出每个字节, 和fsyncs 之前 回来。 如果截断、写入或同步失败,当地索赔即告终结 出现错误。 无视羊群的读者仍可以观察进取 短句/写出顺序;对于写作者来说,保证是完成或错误, 对解锁的读者来说不是原子的旧的或新的能见度.

## 发展

```bash
bun run test
# With Node 24 available:
bun run test:node
bun run typecheck
bun run build
```

## 常见问题

### @bearly/flock 是什么？

本地 macOS 和 Linux 文件系统中 Bun 的 crash- safe fd- hold 羊群所有权

### 如何安装 @bearly/flock？

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

### @bearly/flock 支持 TypeScript 吗？

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

### @bearly/flock 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @bearly/flock 需要什么版本的 Node\.js？

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

### @bearly/flock 可以商用吗？

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

### @bearly/flock 的下载量有多少？

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

### @bearly/flock 还在维护吗？

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