Electron process 对象扩展 API 全解：沙箱可用面、内存监控与平台差异

Electron 在 Node.js 原生 process 对象之上扩展了一批事件、属性与方法，覆盖进程类型判断、V8/Blink 内存统计、系统内存与 CPU 用量查询、堆快照抓取与文件描述符限制调整等能力。本文基于 Electron 官方 API 文档 docs/api/process.md 完整展开这些 API 的语义与使用方式，并结合 shell/common 下的 C++ 绑定源码与 spec 测试用例，说明每个 API 的底层实现、跨进程可用性差异（尤其是沙箱渲染进程下可调用 API 的收缩）以及 Windows/macOS/Linux 之间的平台行为差异。读完本篇，你可以准确判断当前运行在哪个进程类型中、在受限沙箱环境下仍能使用哪些诊断手段，以及如何用源码级证据解释内存/CPU 统计数据的口径。

扩展对象与运行位置

process 对象在主进程与渲染进程中都可用，它是 Node.js process 对象（见 术语表 中 main/renderer 进程定义）的超集，Electron 在其中注入了事件、只读属性与诊断方法。扩展绑定分两层：

• 一组在“沙箱与非沙箱渲染进程之间共享”的绑定（crash、hang、getCreationTime、getHeapStatistics、getBlinkMemoryInfo、getSystemMemoryInfo、getSystemVersion、getCPUUsage），见 shell/common/api/electron_bindings.cc#L43-L70 中 ElectronBindings::BindProcess 的注释“These bindings are shared between sandboxed & unsandboxed renderers”；
• 仅非沙箱环境绑定的扩展（takeHeapSnapshot、setFdLimit、activateUvLoop 等），在同文件 BindTo 中注册（shell/common/api/electron_bindings.cc#L72-L84），其中 setFdLimit 仅在 POSIX 平台（#if BUILDFLAG(IS_POSIX)）下注册，与文档标注的 macOS Linux 限定一致。

沙箱渲染进程下的 API 可用面

在启用沙箱的渲染进程中，process 对象仅保留一个子集 API。文档列出的可用成员为：

方法：crash()、hang()、getCreationTime()、getHeapStatistics()、getBlinkMemoryInfo()、getProcessMemoryInfo()、getSystemMemoryInfo()、getCPUUsage()、uptime()

属性：argv、execPath、env、pid、arch、platform、sandboxed、contextIsolated、type、version、versions、mas、windowsStore、contextId

从源码结构看，这一子集与上文 BindProcess 共享绑定清单一一对应，验证了沙箱环境确实只暴露这组“跨渲染器共享”的绑定。因此设计性能监控、崩溃自检等功能时，应以该子集为最低可用面：getHeapStatistics、getSystemMemoryInfo、getCPUUsage 这类诊断方法在沙箱渲染器中依然可用，可以放心用于渲染端性能上报。

事件

Event: 'loaded'

Electron 加载完其内部初始化脚本、开始加载网页或主脚本时触发。从源码看，该事件在 Node 环境初始化阶段由 shell/common/node_bindings.cc#L1039 通过 gin_helper::EmitEvent(env->isolate(), env->process_object(), "loaded") 发出；沙箱渲染器路径下则由 shell/renderer/electron_sandboxed_renderer_client.cc#L160 调用 InvokeEmitProcessEvent 补发，保证沙箱模式下的事件时序一致。

属性

process.defaultApp Readonly

boolean。当应用是以参数形式传给 Electron 默认可执行文件启动时，主进程中该属性为 true，否则为 undefined。例如执行 electron . 时它为 true，即使应用已打包（app.isPackaged 为 true）。典型用途是判断需要从 process.argv 头部裁掉多少参数：electron . 启动方式下 argv 比打包后直接启动多出一层“解释器”参数，defaultApp 是可靠的判别依据。

process.isMainFrame Readonly

boolean，当前渲染上下文是否为“主”渲染帧时为 true。若需要当前 frame 的 ID，应使用 webFrame.routingId（参见 webFrame API）。

process.mas Readonly

boolean。Mac App Store 构建中为 true，其他构建为 undefined。源码中该属性通过编译期开关注入：shell/common/api/electron_bindings.cc#L62-L64 中 #if IS_MAS_BUILD() 时执行 process->SetReadOnly("mas", true)，因此它是构建期常量，运行期不可变。

process.noAsar

boolean，控制应用内 ASAR 支持。设为 true 会禁用 Node 内置模块对 asar 归档的支持，可用于排查 asar 相关问题。

process.noDeprecation

boolean（可选），控制弃用警告是否打印到 stderr。设为 true 可静默弃用警告。它替代 --no-deprecation 命令行开关。

process.resourcesPath Readonly

string，资源目录的路径。渲染进程内部初始化脚本用它拼装 electron.asar 的位置，见 lib/renderer/init.ts#L102-L103 中 path.join(process.resourcesPath, 'electron.asar', ...) 的用法；主进程同样用它定位打包产物目录（lib/browser/init.ts#L104-L107）。

process.sandboxed Readonly

boolean，渲染进程被沙箱化时为 true，否则为 undefined。是程序判断“当前 API 面是否已收缩到沙箱子集”的直接依据。

process.contextIsolated Readonly

boolean，指示当前渲染上下文是否启用了 contextIsolation；主进程中为 undefined。配合 上下文隔离教程 使用，可动态选择注入方式。

process.throwDeprecation

boolean，控制弃用警告是否作为异常抛出。替代 --throw-deprecation 命令行开关。

process.traceDeprecation

boolean，控制打印到 stderr 的弃用警告是否附带堆栈。替代 --trace-deprecation 命令行开关。

process.traceProcessWarnings

boolean，控制打印到 stderr 的进程警告（包括弃用警告）是否附带堆栈。替代 --trace-warnings 命令行开关。

process.type Readonly

string，当前进程类型，取值：

值	含义
browser	主进程
renderer	渲染进程
service-worker	服务工作者内
worker	Web Worker 内
utility	以服务方式启动的 Node 进程（UtilityProcess）

process.type 是跨模块代码做进程分支（如 IPC 通道选择、诊断逻辑开关）的标准入口。

process.versions.chrome / process.versions.electron Readonly

string，分别为 Chrome 与 Electron 的版本号。做版本相关能力检测（feature detection）时优先查询这两项。

process.windowsStore Readonly

boolean。应用以 MSIX 包（含 Windows Store 的 AppX）方式运行时为 true，否则为 undefined。源码同样按运行环境注入（shell/common/api/electron_bindings.cc#L66-L69：Windows 平台且 IsRunningInDesktopBridge() 时置真）。

process.contextId Readonly

string（可选），当前 JavaScript 上下文的全局唯一 ID。每个 frame 拥有自己的 JS 上下文；启用 contextIsolation 时，隔离世界也有独立上下文。该属性仅在渲染进程可用，可用于日志中标记帧级上下文、排查跨 frame 事件归属问题。

process.parentPort

若当前是 UtilityProcess，这是一个 Electron.ParentPort 实例，用于与父进程通信；其他进程类型为 null。实现见 lib/utility/init.ts#L29-L45：parentPort 被以 Object.defineProperty 挂到 process 上，并且带自动流控——当第一个 message 监听器注册时自动 start()，当监听器数归零时自动 pause()，保证 UtilityProcess 侧消息循环按需启停。

方法

process.crash()

使当前进程主线程崩溃。C++ 侧实现是标准的空指针写入（shell/common/api/electron_bindings.cc#L114-L117：volatile int* zero = nullptr; *zero = 0;），用于测试崩溃上报链路（配合 crash-reporter）。由于该绑定在 BindProcess 共享清单中，沙箱渲染进程同样可用。

process.hang()

使当前进程主线程挂起。实现为一个无限 base::PlatformThread::Sleep 循环（shell/common/api/electron_bindings.cc#L120-L123），用于测试“无响应窗口”检测与强制退出逻辑。

process.getCreationTime()

返回 number | null：进程创建时间（自 epoch 起的毫秒数），取不到时返回 null。实现直接读取 base::Process::Current().CreationTime()，见 shell/common/api/electron_bindings.cc#L155-L162。

process.getCPUUsage()

返回 CPUUsage。

[!NOTE] percentCPUUsage 与 idleWakeupsPerSecond 是自上一次调用 process.getCPUUsage() 以来的均值，每次调用开启新的测量区间，且同一进程内所有调用方共享该区间（详见 CPUUsage 结构）。

源码层面（shell/common/api/electron_bindings.cc#L275-L299）还有两点值得注意的细节：

• percentCPUUsage 由 GetPlatformIndependentCPUUsage 计算后除以 CPU 核数（usagePercent / processor_count）归一化，即单核占比口径；
• idleWakeupsPerSecond 在 Windows 上由 Chromium 的 GetIdleWakeupsPerSecond 抛 NOTIMPLEMENTED()，因此 Electron 为保证向后兼容直接返回 0。

process.getHeapStatistics()

返回 V8 堆统计对象（所有数值单位为 Kilobytes）：

字段	类型	说明
totalHeapSize	Integer	堆总大小
totalHeapSizeExecutable	Integer	可执行堆大小
totalPhysicalSize	Integer	物理内存大小
totalAvailableSize	Integer	可用大小
usedHeapSize	Integer	已用堆大小
heapSizeLimit	Integer	堆大小上限
mallocedMemory	Integer	malloc 内存
peakMallocedMemory	Integer	峰值 malloc 内存
doesZapGarbage	boolean	是否对垃圾区域做填充

实现直接读取 v8::HeapStatistics，并将字节值右移 10 位换算为 KB（shell/common/api/electron_bindings.cc#L126-L152），即源码中的 static_cast<double>(v8_heap_stats.total_heap_size() >> 10) 等行，印证了“以 KB 报告”的口径。

process.getBlinkMemoryInfo()

返回 Blink 内存信息，对调试渲染/DOM 相关内存问题有用（数值单位为 Kilobytes）：

字段	说明
allocated	所有已分配对象的大小（KB）
total	已分配空间总量（KB）

对应实现调用 blink::ProcessHeap::TotalAllocatedObjectSize() 与 TotalAllocatedSpace()（shell/common/api/electron_bindings.cc#L224-L233）。与 getHeapStatistics（V8 堆）互补：JS 堆归 V8 管，DOM/平台对象归 Blink ProcessHeap 管，两者都要看才能完整解释一个渲染进程的内存占用。

process.getProcessMemoryInfo()

返回 Promise<ProcessMemoryInfo>，解析为 ProcessMemoryInfo（数值单位为 Kilobytes），应在 app ready 之后调用。

• Chromium 在 macOS 上不提供 residentSet 值，因为 macOS 会对近期未使用的页面做内存压缩，驻留集大小的读数不符合直觉；此时 private 更能代表压缩前的真实进程内存占用。

底层实现（shell/common/api/electron_bindings.cc#L203-L272）有两条值得了解的证据链：

1. 主进程侧通过 Chromium 的 Memory Instrumentation 机制发起全局内存 dump（RequestGlobalDumpForPid），从 os_dump 中取 resident_set_kb（仅 Linux/Windows 输出）、private_footprint_kb、shared_footprint_kb 三个字段；app 未 ready 时 Promise 会以“Memory Info is available only after app ready”拒绝，这解释了文档“app ready 之后调用”的硬性要求；
2. 从源码结构看，getProcessMemoryInfo 只在 IsBrowserProcess() 分支绑定到 C++ 层，渲染进程侧则通过代理实现——lib/renderer/init.ts#L56 中 process.getProcessMemoryInfo 经 IPC 转给主进程处理，主进程在 lib/browser/rpc-server.ts#L27 以 event.sender._getProcessMemoryInfo() 响应，即渲染端查询的是“本渲染进程”的内存，但实际测量发生在主进程侧。

process.getSystemMemoryInfo()

返回整个系统的内存统计（数值单位为 Kilobytes）：

字段	平台	说明
total	全平台	系统可用物理内存总量
free	全平台	未被应用或磁盘缓存使用的内存
available	Linux	内核估计的无需换页即可分配的内存量，取自 /proc/meminfo 的 MemAvailable。在 Linux 上应以此作为内存压力信号；该平台的 free 对应 MemFree，不含页面缓存等可回收内存
fileBacked	macOS	已换出到存储的内存量，含文件缓存、网络缓冲等系统服务
purgeable	macOS	被标记为“purgeable”的内存，系统内存压力升高时可回收
swapTotal	Windows / Linux	系统交换内存总量
swapFree	Windows / Linux	空闲交换内存量

源码中字段与平台的对应关系（shell/common/api/electron_bindings.cc#L165-L200）：

• free 在 Windows 取 avail_phys，其他平台取 free；
• available 仅 Linux 分支输出（mem_info.available）；
• fileBacked/purgeable 仅 macOS 输出；非 macOS 分支输出 swapTotal/swapFree，且源码注释明确 macOS 上 swap 值是 bogus 的，因此不输出。

测试用例 spec/api-process-spec.ts#L55 对 process.getSystemMemoryInfo() 做了主/渲染双端调用验证。

process.getSystemVersion()

返回 string，宿主操作系统版本：

const version = process.getSystemVersion()
console.log(version)
// On macOS -> '10.13.6'
// On Windows -> '10.0.17763'
// On Linux -> '4.15.0-45-generic'

[!NOTE] 与 os.release() 不同，它在 macOS 上返回的是实际操作系统版本而非内核版本。

实现直接绑定 Chromium 的 base::SysInfo::OperatingSystemVersion（shell/common/api/electron_bindings.cc#L56-L57）。

process.takeHeapSnapshot(filePath)

• filePath string - 输出文件路径。

返回 boolean，指示快照是否创建成功。抓取 V8 堆快照并保存到 filePath。

实现链路为：JS → ElectronBindings::TakeHeapSnapshot（shell/common/api/electron_bindings.cc#L302-L310），内部以 base::File::FLAG_CREATE_ALWAYS | FLAG_WRITE 打开文件，再委托 electron::TakeHeapSnapshot（shell/common/api/electron_api_v8_util.cc#L68-L70）调用 isolate->GetHeapProfiler()->TakeHeapSnapshot()。注意 FLAG_CREATE_ALWAYS 意味着已存在的文件会被覆盖；快照可在 Chrome DevTools 的堆快照分析器中打开查看。

process.setFdLimit(maxDescriptors) macOS Linux

• maxDescriptors Integer

将当前进程的文件描述符软限制设置为 maxDescriptors 或系统硬限制中的较小者。仅在 POSIX 平台注册（源码 #if BUILDFLAG(IS_POSIX) 分支，shell/common/api/electron_bindings.cc#L78-L80），实现即 Chromium 的 base::IncreaseFdLimitTo。TypeScript 类型冒烟测试中的示例用法为 process.setFdLimit(8192)（spec/ts-smoke/electron/main.ts#L1147）。对于需要大量并发文件/Socket 的桌面应用（如本地数据库、日志轮转），在高负载启动前提高该限制是常见手段。

使用建议与验证路径

• 进程分支判断：统一以 process.type + process.sandboxed + process.contextIsolated 组合决定能力集，避免在沙箱渲染器中调用未共享绑定的方法（如 takeHeapSnapshot）；
• 内存诊断口径：JS 堆看 getHeapStatistics（KB），DOM/平台对象看 getBlinkMemoryInfo（KB），整机趋势用 getSystemMemoryInfo（Linux 用 available 而非 free 判断压力），进程级 RSS/私享内存用 getProcessMemoryInfo（macOS 侧重 private）；
• 崩溃与无响应测试：crash()/hang() 是沙箱内外都可用的受控破坏手段，配合崩溃上报与窗口响应性测试使用；
• 可追溯依据：文档为 docs/api/process.md，核心 C++ 绑定见 shell/common/api/electron_bindings.cc 与 shell/common/api/electron_api_v8_util.cc，行为验证可参考 spec/api-process-spec.ts 与类型冒烟测试 spec/ts-smoke/electron/main.ts。