get-port

获取一个可用的 TCP 端口。

安装

npm install get-port

使用方法

import getPort from 'get-port';

console.log(await getPort());
//=> 51402

传入首选端口：

import getPort from 'get-port';

console.log(await getPort({port: 3000}));
// Will use 3000 if available, otherwise fall back to a random port

传入首选端口数组：

import getPort from 'get-port';

console.log(await getPort({port: [3000, 3001, 3002]}));
// Will use any element in the preferred ports array if available, otherwise fall back to a random port

若你需要某个特定范围内的端口，请使用 portNumbers() 辅助函数：

import getPort, {portNumbers} from 'get-port';

console.log(await getPort({port: portNumbers(3000, 3100)}));
// Will use any port from 3000 to 3100, otherwise fall back to a random port

API

getPort(options?)

返回一个用于获取端口号的 Promise。

options

类型：object

port

类型：number | Iterable<number>

首选端口或首选端口的可迭代对象。

exclude

类型：Iterable<number>

不应返回的端口。

例如，你可以将 portNumbers() 函数的返回值传递给它。

reserve

类型：boolean
默认值：false

保留端口，使其在进程的生命周期内保持锁定，而不是默认的 15-30 秒。

当获取端口到实际绑定端口之间存在较长延迟时（例如在长时间运行的测试套件中），这非常有用。

保留的端口会按端口号在当前进程中全局锁定，即使你使用特定的 host 或 ipv6Only 选项查找它们。

使用 clearLockedPorts() 释放保留的端口。

host

类型：string

应在其上执行端口解析的主机。可以是 IPv4 或 IPv6 地址。

默认情况下，它会检查 OS 网络接口 中定义的所有本地地址的可用性。如果设置了此选项，它将仅检查指定的主机。

portNumbers(from, to)

生成给定范围 from...to 内的端口号。

返回给定范围内端口号的 Iterable。

import getPort, {portNumbers} from 'get-port';

console.log(await getPort({port: portNumbers(3000, 3100)}));
// Will use any port from 3000 to 3100, otherwise fall back to a random port

from

类型：number

范围的起始端口。必须在 1024...65535 范围内。

to

类型：number

范围的结束端口。必须在 1024...65535 范围内，且必须大于 from。

clearLockedPorts()

清除已锁定端口的内部缓存，包括使用 reserve 选项锁定的任何端口。

当你希望结果不受之前调用的影响时，此方法会很有用。

请注意，清除缓存会移除针对进程内竞争条件的保护。

import getPort, {clearLockedPorts} from 'get-port';

const port = [3000, 3001, 3002];

console.log(await getPort({port}));
//=> 3000

console.log(await getPort({port}));
//=> 3001

// If you want the results to be unaffected by previous calls, clear the cache.
clearLockedPorts();

console.log(await getPort({port}));
//=> 3000

注意事项

在获取端口号到实际开始使用端口号的这段时间内，如果有其他进程开始使用相同的端口号，可能会存在极小概率的竞争条件。

进程内竞争条件（例如运行并行 Jest 测试时）已通过轻量级锁定机制完全消除，该机制会将返回的端口保留 15-30 秒，之后才允许重新使用。如果从获取端口到绑定端口之间的延迟可能超过此时间窗口（例如在长时间运行的测试套件中），请使用 reserve 选项将端口锁定，直至进程结束。

跨进程竞争条件极为罕见，当尝试绑定端口时，会立即导致 EADDRINUSE 错误，从而允许应用程序重试。

相关链接

• get-port-cli - 本模块的命令行界面