# @alcalzone/proper-lockfile 中文文档

规范地址：https://npmcn.com/package/%40alcalzone/proper-lockfile/

版本：4\.1\.3-0
npm 元数据更新时间：2022-09-06T11:25:07.180Z
中文译文更新时间：2026-11-05T18:16:02.729Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：26 kB，7 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2022-09-06T11:25:06.745Z
- 最新版本发布：2022-09-06T11:25:07.029Z
- 近 30 天下载量：91663（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：1（近 12 个月 0 个）

## 中文简介

一个在本地或网络文件系统上工作的进程间和机器间锁文件工具

## 安装

```sh
npm install @alcalzone/proper-lockfile
```

也可以使用：`pnpm add @alcalzone/proper-lockfile`、`yarn add @alcalzone/proper-lockfile`、`bun add @alcalzone/proper-lockfile`

## README

# 正确锁定文件

[![NPM version](https://img.shields.io/npm/v/proper-lockfile.svg)](https://npmjs.org/package/proper-lockfile) [![Downloads](https://img.shields.io/npm/dm/proper-lockfile.svg)](https://npmjs.org/package/proper-lockfile) [![Build Status](https://img.shields.io/travis/moxystudio/node-proper-lockfile/master.svg)](https://travis-ci.org/moxystudio/node-proper-lockfile) [![Coverage Status](https://img.shields.io/codecov/c/github/moxystudio/node-proper-lockfile/master.svg)](https://codecov.io/gh/moxystudio/node-proper-lockfile) [![Dependency status](https://img.shields.io/david/moxystudio/node-proper-lockfile.svg)](https://david-dm.org/moxystudio/node-proper-lockfile) [![Dev Dependency status](https://img.shields.io/david/dev/moxystudio/node-proper-lockfile.svg)](https://david-dm.org/moxystudio/node-proper-lockfile?type=dev)

一个在本地或网络文件系统中工作的跨进程和跨机器锁文件工具.

## 安装

`$ npm install proper-lockfile`

## 设计

有多种方法可以实现 [文件锁定](http://en.wikipedia.org/wiki/File_locking)。 。 。 .

这个图书馆使用 `mkdir` 任何类型的文件系统 甚至是基于网络的系统. 锁定文件路径基于您试图用后缀锁定的文件路径 `.lock`。 。 。 .

当锁被成功获取时, 锁文件是 `mtime` (修改后的时间)定期更新,以防止停滞. 这样可以有效检查锁是否通过检查其 `mtime` 与坚固的门槛相抗衡。 如果mtime的更新失败了好几次,锁可能会被损坏. 这个 `mtime` 实值 [支持](http://en.wikipedia.org/wiki/Comparison_of_file_systems) 几乎每笔 `filesystem`。 。 。 .

### 比较

这个图书馆类似于 [锁定文件](https://github.com/isaacs/lockfile) 但后者有一些缺点:

-   它依赖 `open` 与 `O_EXCL` 在网络文件系统中有问题的旗帜. `proper-lockfile` 用途 `mkdir` 它没有这个问题.

> O EXCL在NFS文件系统中被打破;依靠它执行锁定任务的程序将包含一个种族条件.

-   锁文件 Staleness 检查是通过 `ctime` 不适合长期运行的过程. `proper-lockfile` 不断更新锁文件 `mtime` 来检查一下状况.
    
-   它不检查锁文件是否被泄露,从而可能导致不良情况. `proper-lockfile` 更新时检查锁定文件 `mtime`。 。 。 .
    
-   它的默认值为 `0` 因为任何崩溃或过程会杀死 包不能优雅地处理 就会永远离开锁.
    

### 妥协

`proper-lockfile` 未发现以下情况:

-   A 类 `lockfile` 手动取出,其他人在紧接着获得锁
-   不同 `stale`编号 :`update` 同一文件使用的值, 可能导致在同一文件上获取两个锁定

`proper-lockfile` 检测下列情况:

-   更新 `lockfile` 失败
-   更新所需时间比预期的要长,可能使锁在一定时间内僵化

如所见前二由用相坏故. 从技术上讲,可以探测到前两种情况,但会引入复杂性和最终的种族条件.

## 使用量

### .lock( 文件, \[选项\])

尝试获取锁定 `file` 或否认警告者.

如果锁成功,a `release` 函数提供在要释放锁时应当调用。 这个 `release` 函数还拒绝错误时的许诺(例如,当锁已经失密时).

可用的选项 :

-   `stale`: 以毫秒计的持续时间,其中锁被视为已停用,默认为 `10000` (最低值为 `5000`(中文(简体) )
-   `update`: 以毫秒表示的锁文件间隔 `mtime` 将更新,默认为 `stale/2` (最低值为 `1000`,最大值为 `stale/2`(中文(简体) )
-   `retries`: 重复次数或次数 [重试](https://www.npmjs.org/package/retry) 选项对象,默认为 `0`
-   `realpath`: 使用 realpath 解析相链接,默认为 `true` (注意如果 `true`,则 `file` 必须是先前存在的)
-   `fs`: 要使用的自定义 fs, 默认为 `graceful-fs`
-   `onCompromised`: 如果锁被损坏, 调用时默认为只丢出可能导致进程失效的错误的函数
-   `lockfilePath`: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 `file` 作为 `<dir path>` 财务报告和审定财务报表 `options.lockfilePath` 作为 `<dir path>/dir.lock`

```js
const lockfile = require('proper-lockfile');

lockfile.lock('some/file')
.then((release) => {
    // Do something while the file is locked

    // Call the provided release function when you're done,
    // which will also return a promise
    return release();
})
.catch((e) => {
    // either lock could not be acquired
    // or releasing it failed
    console.error(e)
});

// Alternatively, you may use lockfile('some/file') directly.
```

### .unlock(文件,\[选项\])

释放先前获得的锁定 `file` 或否认警告者.

尽可能使用 `release` 函数代替(如上所示)。 仍然有一些情况下,很难在代码周围保持引用. 在这种情况下 `unlock()` 可能比较方便.

可用的选项 :

-   `realpath`: 使用 realpath 解析相链接,默认为 `true` (注意如果 `true`,则 `file` 必须是先前存在的)
-   `fs`: 要使用的自定义 fs, 默认为 `graceful-fs`
-   `lockfilePath`: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 `file` 作为 `<dir path>` 财务报告和审定财务报表 `options.lockfilePath` 作为 `<dir path>/dir.lock`

```js
const lockfile = require('proper-lockfile');

lockfile.lock('some/file')
.then(() => {
    // Do something while the file is locked

    // Later..
    return lockfile.unlock('some/file');
});
```

### 检查(文件,\[选项\])

检查文件是否被锁定且其锁文件不呆滞, 拒绝错误的保证 .

可用的选项 :

-   `stale`: 以毫秒计的持续时间,其中锁被视为已停用,默认为 `10000` (最低值为 `5000`(中文(简体) )
-   `realpath`: 使用 realpath 解析相链接,默认为 `true` (注意如果 `true`,则 `file` 必须是先前存在的)
-   `fs`: 要使用的自定义 fs, 默认为 `graceful-fs`
-   `lockfilePath`: 自定义锁文件路径 。 例如: 如果您想要锁定目录并创建其中的锁文件, 您可以通过 `file` 作为 `<dir path>` 财务报告和审定财务报表 `options.lockfilePath` 作为 `<dir path>/dir.lock`

```js
const lockfile = require('proper-lockfile');

lockfile.check('some/file')
.then((isLocked) => {
    // isLocked will be true if 'some/file' is locked, false otherwise
});
```

### .lockSync(文件,\[选项\])

同步版本 `.lock()`。 。 。 .  
返回 `release` 函数或投放出错.

### . 解锁同步( 文件, \[选项\])

同步版本 `.unlock()`。 。 。 .  
投出出错.

### 。checkSync(文件,\[选项\])

同步版本 `.check()`。 。 。 . 返回布尔或投出错误.

## 优雅的离开

`proper-lockfile` 如果进程退出,则自动去除锁,除非进程与SIGKILL一起被杀死,或者由于VM致命错误而崩溃(如:出自内存).

## 测试

`$ npm test`  
`$ npm test -- --watch` 开发期间

测试套房非常广泛. 甚至有压力测试来保证锁的专属性.

## 许可证

释放 [MIT 许可证](https://www.opensource.org/licenses/mit-license.php)。 。 。 .

## 常见问题

### @alcalzone/proper-lockfile 是什么？

一个在本地或网络文件系统上工作的进程间和机器间锁文件工具

### 如何安装 @alcalzone/proper-lockfile？

在项目目录运行 npm install @alcalzone/proper-lockfile，或使用 pnpm add / yarn add / bun add。

### @alcalzone/proper-lockfile 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/alcalzone\_\_proper-lockfile 是否存在。

### @alcalzone/proper-lockfile 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @alcalzone/proper-lockfile 可以商用吗？

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

### @alcalzone/proper-lockfile 的下载量有多少？

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

### @alcalzone/proper-lockfile 还在维护吗？

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