# @bybrave/proper-lockfile2 中文文档 规范地址：https://npmcn.com/package/%40bybrave/proper-lockfile2/ 版本：5\.1\.0 npm 元数据更新时间：2026-10-13T22:41:46.952Z 中文译文更新时间：2026-11-08T21:11:07.147Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40bybrave/proper-lockfile2 原文对照：https://npmcn.com/package/%40bybrave/proper-lockfile2/?lang=original 项目主页：https://github.com/bybraveHQ/proper-lockfile2#readme 源码仓库：https://github.com/bybraveHQ/proper-lockfile2 ## 关键信息（来自 npm 元数据） - 包体积（解压后）：31.3 kB，8 个文件 - 模块格式：CommonJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18 - 运行依赖：3 个 - 首次发布：2026-07-04T21:44:56.317Z - 最新版本发布：2026-10-13T22:41:46.775Z - 近 30 天下载量：55734（2026-10-09 至 2026-11-07，npm 官方下载统计） - 已发布版本数：2（近 12 个月 2 个） ## 中文简介 维护了正锁文件的叉子——一种在本地或网络文件系统中工作的跨进程和机器间锁文件工具 ## 安装 ```sh npm install @bybrave/proper-lockfile2 ``` 也可以使用：`pnpm add @bybrave/proper-lockfile2`、`yarn add @bybrave/proper-lockfile2`、`bun add @bybrave/proper-lockfile2` ## README # @ bybrave/ proper- lock file2 [![CI](https://github.com/bybraveHQ/proper-lockfile2/actions/workflows/ci.yml/badge.svg)](https://github.com/bybraveHQ/proper-lockfile2/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@bybrave/proper-lockfile2.svg)](https://www.npmjs.com/package/@bybrave/proper-lockfile2) [![node](https://img.shields.io/node/v/@bybrave/proper-lockfile2.svg?color=339933&logo=node.js&logoColor=white)](https://www.npmjs.com/package/@bybrave/proper-lockfile2) [![types](https://img.shields.io/badge/types-included-3178C6?logo=typescript&logoColor=white)](https://npmcn.com/package/%40bybrave/proper-lockfile2/index.d.ts) [![license](https://img.shields.io/npm/l/@bybrave/proper-lockfile2.svg?color=blue)](https://npmcn.com/package/%40bybrave/proper-lockfile2/LICENSE) 维护的叉 [正确锁定文件](https://github.com/moxystudio/node-proper-lockfile) ——一个在本地或网络文件系统上工作的跨进程和相机锁文件工具. ## 为何这个叉子 原画 `proper-lockfile` 2021年起一直未出狱. 这个叉子是一个倒置的替换,它修正了真正的双锁赛车和最需要的船: | 变动 | 上游问题 | | --- | --- | | **固定 Stale-lock 回收赛**:两个过程既可以"收回"同一种 stale 锁并最后同时持有 | [121号](https://github.com/moxystudio/node-proper-lockfile/issues/121), 造成许多 [92号](https://github.com/moxystudio/node-proper-lockfile/issues/92) 报告 | | `onReclaimed` 调回: 要知道您锁是何时通过回收一个已失效的锁来获取的( 例如运行一次精确的崩溃恢复) | [105号](https://github.com/moxystudio/node-proper-lockfile/issues/105) | | `ELOCKED` 错误消息现在提示到 `retries` 选项——最常见的混淆来源 | [92号](https://github.com/moxystudio/node-proper-lockfile/issues/92) | | Ctrl-C 和 (简体中文) `SIGTERM` 继续工作: 退出处理器安装在第一个获得的锁上, 而不是打开 `require` | [111号](https://github.com/moxystudio/node-proper-lockfile/issues/111), (中文(简体) ), [110号](https://github.com/moxystudio/node-proper-lockfile/issues/110) | | 没有 `Cannot read properties of undefined (reading 'updateTimeout')` 在重试时间更新时, 当锁定发布时崩溃 | [113号](https://github.com/moxystudio/node-proper-lockfile/issues/113) | | `onCompromised: undefined` 编号 : `null` 保留默认处理器而不是崩溃 | [117号](https://github.com/moxystudio/node-proper-lockfile/pull/117) | | mtime精度被检测到每个设备,所以在一个过程中锁定不同精度工作的文件系统 | [104号](https://github.com/moxystudio/node-proper-lockfile/pull/104) | | 包含类型脚本类型定义 | —— 说 | | 更新的依赖性,CI on Node 18/20/22,原测试套件被保留(76个测试)+每个固定的回归测试 | —— 说 | ### 比赛,简而言之 上游恢复了坚固的锁 `rmdir` + 键 `mkdir`如果进程A检测到一个已失效的锁,但在程序A检测到它之前会拖住 `rmdir`,过程B可以回收锁并创建新的锁——A的后期 `rmdir` 然后悄悄地删除,两个过程都相信它们拥有锁. 这叉子声称在解剖学上是坚固的锁 **重命名** 它们通往一个独特的路径(只有一个进程可以赢得一个重命名),并且验证所声称的目录仍然是它看到的被扭曲的目录. 复制脚本和回归测试正在进行中 [`test/fork.test.js`](https://npmcn.com/package/%40bybrave/proper-lockfile2/test/fork.test.js)。 。 。 . ## 安装 ```sh npm install @bybrave/proper-lockfile2 ``` ## 使用量 ```js const lockfile = require('@bybrave/proper-lockfile2'); const release = await lockfile.lock('some/file'); // do your critical work... await release(); ``` 等待锁定而不是失败: ```js const release = await lockfile.lock('some/file', { retries: { retries: 5, maxTimeout: 1000 }, }); ``` 当一个 stale 锁( 由已死进程留下) 被回收时运行崩溃恢复 : ```js const release = await lockfile.lock('some/file', { onReclaimed: () => runRecovery(), }); ``` 同步 API : `lockSync`, (中文(简体) ), `unlockSync`, (中文(简体) ), `checkSync` (不支持同步模式的重复). ## API 密码 ### 锁定( 文件, \[选项\]) —— 承诺 < 释放 > 锁定锁定 `file`,以 `release()` 函数。 拒绝使用 `ELOCKED` 如果锁被锁住(而不是被锁住). | 选项 | 默认 | 说明 | | --- | --- | --- | | `stale` | `10000` | 之后,一个未更新的锁被视为 stale (min `2000`(中文(简体) ) | | `update` | `stale/2` | 锁文件 mtime 刷新间隔 `1000`最大点 `stale/2`(中文(简体) ) | | `retries` | `0` | 复试次数(或 [节点重试](https://github.com/tim-kos/node-retry) 选项对象),同时获取被扣锁 | | `realpath` | `true` | 解析并联; 设置 `false` 以锁定链接本身(也允许锁定已存在的路径) | | `onCompromised` | `(err) => { throw err; }` | 当锁无法保证时调用 | | `onReclaimed` | —— 说 | 在锁被取回时被调用 | | `lockfilePath` | `${file}.lock` | 自定义锁定文件位置 | | `fs` | `graceful-fs` | 自定义 fs 执行 | #### 锁定一个尚未存在的文件 默认 `realpath: true` 文件必须存在, 因为 `realpath` 解决整个路径的符号链接。 当将一个未创建的文件锁定在像“ ” 这样的共线目录下时, 也会显示此信息 `/tmp` 在macOS上(指 `/private/tmp`),与 `ENOENT` (单位:千美元)[一百块](https://github.com/moxystudio/node-proper-lockfile/issues/100), (中文(简体) ), [99号](https://github.com/moxystudio/node-proper-lockfile/issues/99)) (中文(简体) ). 要么先创建文件, 要么通过 `realpath: false`. 权衡 `realpath: false`:锁被所写的路径所键入,因此有两个过程通过不同的同名链接到达同一个文件(`/tmp/foo` 财务报告和审定财务报表 `/private/tmp/foo`)将不相见相锁. 在所有过程中使用一条犬道,例如:. `fs.realpathSync(dir) + '/file'` 对于已存在的目录. ### 解锁(文件,\[选项\])/检查(文件,\[选项\])-承诺 与原文相同的语义: `unlock` 释放在这个过程中获得的锁, `check` 解决当前是否锁定文件。 选项 : `stale` (仅检查), `realpath`, (中文(简体) ), `lockfilePath`, (中文(简体) ), `fs`。 。 。 . 完整的概念文件(基于时间的锁定工作、其保障和警告)载于 [原始读取器](https://github.com/moxystudio/node-proper-lockfile#readme) ——设计不变. ## 从正锁文件移走 它是一个临时替代: ```diff - const lockfile = require('proper-lockfile'); + const lockfile = require('@bybrave/proper-lockfile2'); ``` 没有删除或更改 API ; `onReclaimed` 这是唯一的新选项。 与原作不同,要求模块在获得锁之前不再订阅处理信号. ## 支助 如果此软件包节省了您的时间, 您可以支持维护 : [![Ko-fi](https://img.shields.io/badge/Ko--fi-buy%20me%20a%20coffee-FF5E5B?logo=kofi&logoColor=white)](https://ko-fi.com/bybrave) [![Bitcoin](https://img.shields.io/badge/Bitcoin-BTC-F7931A?logo=bitcoin&logoColor=white)](https://npmcn.com/package/%40bybrave/proper-lockfile2/#readme-support) 比特币( BTC): `bc1q37557q5jpeaxqydzwvf3jgj7zhnfpn2td3q40q` ## 信贷和许可证 麻省理工学院. 依据 [正确锁定文件](https://github.com/moxystudio/node-proper-lockfile) 由André Cruz/MOXY编著. ## 常见问题 ### @bybrave/proper-lockfile2 是什么？ 维护了正锁文件的叉子——一种在本地或网络文件系统中工作的跨进程和机器间锁文件工具 ### 如何安装 @bybrave/proper-lockfile2？ 在项目目录运行 npm install @bybrave/proper-lockfile2，或使用 pnpm add / yarn add / bun add。 ### @bybrave/proper-lockfile2 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @bybrave/proper-lockfile2 支持 ESM 还是 CommonJS？ 以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。 ### @bybrave/proper-lockfile2 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @bybrave/proper-lockfile2 可以商用吗？ @bybrave/proper-lockfile2 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @bybrave/proper-lockfile2 的下载量有多少？ 根据 npm 官方下载统计，@bybrave/proper-lockfile2 在 2026/10/09 – 2026/11/07 这 30 天内被下载 55,734 次，日均约 1,858 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @bybrave/proper-lockfile2 还在维护吗？ 最新版本 5\.1\.0 发布于 2026/10/14（25 天前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/07/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。