utils | ElectronEgg

简介

工具函数集合。提供对象深度合并、环境检测、JSON 文件操作、IP/端口工具和常用辅助函数。所有子模块 API 统一在 ee-core/utils 导出路径下。

参见：ps 进程状态与路径工具 | helper（同一页面）

导入

javascript

// ESM
import { extend, is, strictParse, fnDebounce, getPort, publicIpv4 } from 'ee-core/utils';

// CJS
const { extend, is, strictParse, fnDebounce, getPort, publicIpv4 } = require('ee-core/utils');

所有子模块函数（extend、is、json、pargv、wrap、helper、port、ip）和顶层函数（getPackage、getMAC、machineId 等）均可通过 ee-core/utils 导入。

顶层函数

getPackage()

读取并解析项目根目录的 package.json。

返回值：unknown — 解析后的 package.json 对象。

示例：

javascript

const pkg = getPackage();
console.log(pkg.name, pkg.version);

getMAC(iface?)

获取第一个有效 MAC 地址。遍历本地网络接口，跳过零 MAC 地址（虚拟接口）。

参数：

参数	类型	必填	说明
`iface`	`string`	否	指定网络接口名称；省略时遍历所有接口

返回值：string — 第一个有效 MAC 地址。

抛出：指定接口不存在、无有效 MAC 或全局无有效 MAC 时抛出异常。

isMAC(macAddress)

检查输入是否为有效 MAC 地址格式（XX:XX:XX:XX:XX:XX 或 XX-XX-XX-XX-XX-XX）。

参数：

参数	类型	必填	说明
`macAddress`	`string`	是	要检查的字符串

返回值：boolean

machineIdSync(original?)

同步获取机器唯一标识（哈希值）。

参数：

参数	类型	必填	说明
`original`	`boolean`	否	返回原始值而非 SHA-256 哈希。默认：`false`

返回值：string — 机器唯一标识。

machineId(original?)

异步获取机器唯一标识（哈希值）。适用于不想阻塞事件循环的场景。

参数：

参数	类型	必填	说明
`original`	`boolean`	否	返回原始值而非 SHA-256 哈希。默认：`false`

返回值：Promise<string> — 机器唯一标识。

getPlatform(delimiter?, isDiffArch?)

获取平台标识字符串，用于构建产物命名和平台检测。

参数：

参数	类型	必填	说明
`delimiter`	`string`	否	分隔符。默认：`'_'`
`isDiffArch`	`boolean`	否	区分架构位数（仅 Windows）。默认：`false`

返回值：string — 平台标识（如 'windows_64'、'macos_apple'、'linux'）。

isFileProtocol(protocol)

检查协议是否为 file://。

参数：

参数	类型	必填	说明
`protocol`	`string`	是	协议字符串

返回值：boolean

isWebProtocol(protocol)

检查协议是否为 http:// 或 https://。

参数：

参数	类型	必填	说明
`protocol`	`string`	是	协议字符串

返回值：boolean

isJsProject(baseDir)

检查项目是否为 JavaScript 项目（非 TypeScript）。通过检查 electron/main.js 或 electron/index.js 是否存在来判断。

参数：

参数	类型	必填	说明
`baseDir`	`string`	是	项目根目录

返回值：boolean

extend

对象深度合并工具。框架配置层合并的核心实现。

extend(deep, target, ...sources)

将多个源对象的属性合并到目标对象。

参数：

参数	类型	必填	说明
`deep`	`boolean \| ExtendOptions`	是	是否深度合并。`true` = 对普通对象递归合并
`target`	`T`	是	目标对象，合并结果写入此处
`sources`	`Array<Partial<T>>`	否	源对象，按顺序合并

返回值：T — 合合后的目标对象。

合并规则：

浅合并（deep=false）：源属性直接覆盖目标
深合并（deep=true）：普通对象递归合并，非普通对象覆盖
跳过 __proto__（防止原型污染）
跳过 undefined 值
检测自引用（防止无限递归）

示例：

javascript

// 浅合并
extend(false, { a: 1 }, { a: 2, b: 3 }); // { a: 2, b: 3 }

// 深合并
extend(true, { a: { x: 1 } }, { a: { y: 2 } }); // { a: { x: 1, y: 2 } }

is

Electron 运行时环境检测。以命名空间对象导出。

javascript

// ESM
import { is } from 'ee-core/utils';
if (is.all(is.main, is.osx)) { /* 主进程 + macOS */ }

// CJS
const { is } = require('ee-core/utils');

检测函数

函数	返回值	说明
`is.renderer()`	`boolean`	当前在渲染进程（`process.type === 'renderer'`）
`is.main()`	`boolean`	当前在主进程（`process.type === 'browser'`）
`is.osx()`	`boolean`	操作系统为 macOS（`process.platform === 'darwin'`）
`is.macOS()`	`boolean`	`osx()` 的别名
`is.windows()`	`boolean`	操作系统为 Windows（`process.platform === 'win32'`）
`is.linux()`	`boolean`	操作系统为 Linux
`is.openharmony()`	`boolean`	操作系统为 OpenHarmony
`is.x86()`	`boolean`	处理器为 x86（32 位，`process.arch === 'ia32'`）
`is.x64()`	`boolean`	处理器为 x64（64 位，`process.arch === 'x64'`）
`is.sandbox()`	`boolean`	在 macOS 沙箱中运行
`is.mas()`	`boolean`	Mac App Store 构建（`process.mas === true`）
`is.windowsStore()`	`boolean`	Windows Store 构建（`process.windowsStore === true`）

组合器

函数	签名	说明
`is.all(...fn)`	`(...() => boolean) => boolean \| undefined`	所有条件为真
`is.none(...fn)`	`(...() => boolean) => boolean \| undefined`	所有条件为假
`is.one(...fn)`	`(...() => boolean) => boolean \| undefined`	至少一个条件为真

示例：

javascript

if (is.all(is.main, is.osx)) {
  // 仅在 macOS 主进程运行
}

if (is.none(is.renderer, is.windows)) {
  // 不是渲染进程，不是 Windows
}

json

JSON 文件读写工具。提供同步和异步操作。

strictParse(str)

解析 JSON 字符串并验证结果必须是对象。

参数：

参数	类型	必填	说明
`str`	`string`	是	JSON 字符串

返回值：unknown — 解析后的对象。

抛出：结果不是对象类型时抛出异常。

readSync(filepath)

同步读取并解析 JSON 文件。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	JSON 文件路径

返回值：unknown — 解析后的对象。

抛出：文件不存在时抛出异常。

writeSync(filepath, str, options?)

同步写入 JSON 文件。自动创建目标目录。默认 2 空格缩进。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	目标文件路径
`str`	`unknown`	是	要写入的内容（对象自动序列化）
`options`	`JsonWriteOptions`	否	`{ space?: number, replacer?: Function }`

返回值：void

read(filepath)

异步读取并解析 JSON 文件。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	JSON 文件路径

返回值：Promise<unknown> — 解析后的对象。

write(filepath, str, options?)

异步写入 JSON 文件。自动创建目标目录。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	目标文件路径
`str`	`unknown`	是	要写入的内容
`options`	`JsonWriteOptions`	否	`{ space?: number, replacer?: Function }`

返回值：Promise<void>

helper

常用工具函数集合。

fnDebounce()

创建防抖包装器工厂。返回一个函数，对传入的任何函数应用防抖控制。

返回值：防抖包装函数，签名为 (fn, delayTime?, isImedite?, args?) => void

示例：

javascript

const debounce = fnDebounce();
debounce(myFunction, 300, false, data);  // 防抖
debounce(myFunction, 0, true, data);     // 立即执行（无防抖）

getRandomString()

生成约 10 个字符的随机字母数字字符串。不适用于安全场景。

返回值：string（如 'x3k9m2a1b5'）

mkdir(filepath, opt?)

递归创建目录。已存在时不报错（等同于 mkdir -p）。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	目录路径
`opt`	`{ mode?: number }`	否	目录权限

返回值：void

chmodPath(filepath, mode)

递归修改文件和目录权限。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	目标目录路径
`mode`	`number`	是	权限值（如 `0o755`）

返回值：void

compareVersion(v1, v2)

比较两个语义版本号。

参数：

参数	类型	必填	说明
`v1`	`string`	是	第一个版本（如 `'1.2.3'`）
`v2`	`string`	是	第二个版本（如 `'1.3.0'`）

返回值：number — v1 > v2 时为 1，v1 < v2 时为 -1，相等时为 0。

stringify(obj, ignore?)

将对象序列化为 JSON 字符串，排除指定字段。

参数：

参数	类型	必填	说明
`obj`	`Record<string, unknown>`	是	要序列化的对象
`ignore`	`string[]`	否	要排除的属性名

返回值：string — 过滤后的 JSON 字符串。

validValue(value)

检查值是否非 null、非 undefined 且非空字符串。

参数：

参数	类型	必填	说明
`value`	`unknown`	是	要检查的值

返回值：boolean

checkConfig(prop)

检查项目根目录下是否存在配置文件。

参数：

参数	类型	必填	说明
`prop`	`string`	是	相对于项目根目录的文件路径

返回值：boolean

sleep(ms)

异步休眠。返回在指定毫秒后 resolve 的 Promise。

参数：

参数	类型	必填	说明
`ms`	`number`	是	休眠时间（毫秒）

返回值：Promise<void>

systemSleep(ms)

同步阻塞休眠。阻塞当前线程。不适用于渲染进程（会冻结 UI）。

参数：

参数	类型	必填	说明
`ms`	`number`	是	休眠时间（毫秒），必须 >= 0

返回值：void

实现：优先使用 Atomics.wait（零 CPU），回退到忙等待循环。

replaceArgsValue(argv, key, value)

替换命令行参数数组中的 key=value 参数。

参数：

参数	类型	必填	说明
`argv`	`string[]`	是	参数数组
`key`	`string`	是	参数键名
`value`	`string`	是	新值

返回值：string[] — 修改后的 argv 数组。

示例：

javascript

replaceArgsValue(['--port=8080', '--env=dev'], 'port', '9090')
// => ['--port=9090', '--env=dev']

getValueFromArgv(argv, key)

从命令行参数中获取指定键的值。

参数：

参数	类型	必填	说明
`argv`	`string[]`	是	参数数组
`key`	`string`	是	键名

返回值：unknown — 值或未找到时为 undefined。

fileIsExist(filepath)

检查文件是否存在（基于 stat）。

参数：

参数	类型	必填	说明
`filepath`	`string`	是	文件路径

返回值：boolean

port

带锁定机制的 TCP 端口分配工具。

getPort(options?)

查找可用 TCP 端口。

参数：

参数	类型	必填	说明
`options`	`GetPortOptions`	否	端口搜索选项

GetPortOptions：

字段	类型	说明
`port`	`number \| number[]`	首选端口或范围。`0` = 操作系统自动分配
`host`	`string`	绑定主机。未指定 = 检查所有接口

返回值：Promise<number> — 可用端口编号。

示例：

javascript

const port = await getPort();                    // 操作系统自动分配
const port = await getPort({ port: 3000 });      // 尝试 3000，被占用时自动查找
const port = await getPort({ port: [3000, 3001] }); // 尝试列表

releasePortLocks()

清理端口锁资源（轮转定时器 + 锁定端口集合）。在应用关闭时调用。

返回值：void

ip

公共 IP 地址查询工具。支持 DNS、HTTPS 和组合查询方式。

publicIpv4(options?)

查询公共 IPv4 地址。

参数：

参数	类型	必填	说明
`options`	`IpOptions`	否	`{ type?: 'http'

返回值：Promise<string> & { cancel?: () => void } — IPv4 地址，带取消方法。

示例：

javascript

const p = publicIpv4({ type: 'http', timeout: 5000 });
const ip = await p;
// 或取消：p.cancel();

publicIpv6(options?)

查询公共 IPv6 地址。选项和返回类型与 publicIpv4 相同。

返回值：Promise<string> & { cancel?: () => void } — IPv6 地址，带取消方法。

配置

前端模块

通信

数据库

任务

Go

Java

Python

简介 ​

导入 ​

顶层函数 ​

getPackage() ​

getMAC(iface?) ​

isMAC(macAddress) ​

machineIdSync(original?) ​

machineId(original?) ​

getPlatform(delimiter?, isDiffArch?) ​

isFileProtocol(protocol) ​

isWebProtocol(protocol) ​

isJsProject(baseDir) ​

extend ​

extend(deep, target, ...sources) ​

is ​

检测函数 ​

组合器 ​

json ​

strictParse(str) ​

readSync(filepath) ​

writeSync(filepath, str, options?) ​

read(filepath) ​

write(filepath, str, options?) ​

helper ​

fnDebounce() ​

getRandomString() ​

mkdir(filepath, opt?) ​

chmodPath(filepath, mode) ​

compareVersion(v1, v2) ​

stringify(obj, ignore?) ​

validValue(value) ​

checkConfig(prop) ​

sleep(ms) ​

systemSleep(ms) ​

replaceArgsValue(argv, key, value) ​

getValueFromArgv(argv, key) ​

fileIsExist(filepath) ​

port ​

getPort(options?) ​

releasePortLocks() ​

ip ​

publicIpv4(options?) ​

publicIpv6(options?) ​

简介

导入

顶层函数

getPackage()

getMAC(iface?)

isMAC(macAddress)

machineIdSync(original?)

machineId(original?)

getPlatform(delimiter?, isDiffArch?)

isFileProtocol(protocol)

isWebProtocol(protocol)

isJsProject(baseDir)

extend

extend(deep, target, ...sources)

is

检测函数

组合器

json

strictParse(str)

readSync(filepath)

writeSync(filepath, str, options?)

read(filepath)

write(filepath, str, options?)

helper

fnDebounce()

getRandomString()

mkdir(filepath, opt?)

chmodPath(filepath, mode)

compareVersion(v1, v2)

stringify(obj, ignore?)

validValue(value)

checkConfig(prop)

sleep(ms)

systemSleep(ms)

replaceArgsValue(argv, key, value)

getValueFromArgv(argv, key)

fileIsExist(filepath)

port

getPort(options?)

releasePortLocks()

ip

publicIpv4(options?)

publicIpv6(options?)