zhaoweiguo 的知识库

Electron 07 环境变量速查

6分钟阅读

07 · 环境变量速查

目标：一网打尽影响 Electron 的环境变量——安装下载、运行时行为、调试日志三大类。 官方对应：环境变量、安装指南

Electron 的很多行为由环境变量控制，因为它们比命令行参数和代码更早初始化。设置方式：

# POSIX
export ELECTRON_ENABLE_LOGGING=true
electron .
 
# Windows
set ELECTRON_ENABLE_LOGGING=true
electron .

一、安装 / 下载相关（@electron/get，国内最常用）

变量作用示例
ELECTRON_MIRROR二进制下载镜像基础路径https://npmmirror.com/mirrors/electron/
ELECTRON_CUSTOM_DIR镜像内的子目录模板，默认 {{ version }}v{{ version }}（镜像保留了 v 前缀时）
ELECTRON_CUSTOM_FILENAME完全自定义文件名模板自建镜像命名规范不同时用
ELECTRON_CACHEelectron 包 postinstall 的下载缓存目录（见下方「下载缓存」）磁盘紧张或换缓存盘时改
ELECTRON_GET_USE_PROXY走系统代理（HTTPS_PROXY/HTTP_PROXY）下载true
ELECTRON_GET_HEADERS下载时附加自定义请求头（JSON）私有镜像鉴权
ELECTRON_BUILDER_BINARIES_MIRRORelectron-builder 辅助二进制镜像（nsis、winCodeSign 等）https://npmmirror.com/mirrors/electron-builder-binaries/
ELECTRON_BUILDER_CACHEelectron-builder 的下载缓存目录（Electron 发行版 + 辅助二进制）见下方「下载缓存」
ELECTRON_INSTALL_PLATFORM安装时手动指定目标平台ELECTRON_INSTALL_PLATFORM=win32 npm install（mac 上装 Windows 二进制）
ELECTRON_INSTALL_ARCH安装时手动指定架构ELECTRON_INSTALL_ARCH=arm64 npm install（Rosetta 下无效）

这些变量在 .npmrc 里也可写小写蛇形形式（如 electron_mirror=...），npm 会自动注入为 npm_config_electron_mirror——但注意两点：

  1. 只有经 npm script 执行时才注入，直接跑 electron . 不会（见 01-quick-start 常见坑）
  2. npm 11+ 已警告该机制将在下一个大版本移除（Unknown project config "electron_mirror"），长期建议直接用 shell 环境变量 ELECTRON_MIRROR=...

下载缓存（两层，均为用户级目录，跨项目/跨构建复用）

下载内容WindowsmacOSLinux覆盖变量
electron 包 postinstall 下载的 electron.zip%LOCALAPPDATA%\electron\Cache~/Library/Caches/electron~/.cache/electronELECTRON_CACHE
electron-builder 拉取的 Electron 发行版 + winCodeSign/NSIS 等%LOCALAPPDATA%\electron-builder\Cache~/Library/Caches/electron-builder~/.cache/electron-builderELECTRON_BUILDER_CACHE

要点：

  • 两层缓存相互独立：npm install electron 命中第一层，electron-builder 打包命中第二层
  • 缓存命中时不再下载，同版本多项目共享，是 CI 加速的关键（缓存这两个目录）
  • 下载损坏/换镜像后不生效时，先删对应缓存目录再重装

二、生产 / 运行时行为

变量平台作用
NODE_OPTIONS全透传 Node CLI 参数（--max-old-space-size=2048 等）。打包后的应用大部分选项被禁用，仅 --max-http-header-size、--http-parser 可用；与 BoringSSL 冲突的 OpenSSL 类选项永远不支持。若关闭了 nodeOptions Fuse 则完全忽略
NODE_EXTRA_CA_CERTS全追加自定义 CA 证书（企业内网 HTTPS 证书场景）；同样受 nodeOptions Fuse 控制
GOOGLE_API_KEY全地理定位功能必需的 Google API key；也可在主进程里 process.env.GOOGLE_API_KEY = ...，需在打开窗口前设置
ELECTRON_RUN_AS_NODE全把 Electron 二进制当普通 Node 进程跑。⚠️ 安全敏感，可被利用执行任意命令，生产建议关 runAsNode Fuse
ELECTRON_NO_ASAR全禁用 ASAR；仅在 ELECTRON_RUN_AS_NODE 的派生子进程中生效
ELECTRON_NO_ATTACH_CONSOLEWindows不附加到当前控制台会话
ELECTRON_FORCE_WINDOW_MENU_BARLinux不用全局菜单栏，改用窗口内菜单栏
ELECTRON_TRASHLinux选择回收站实现：gio（默认）/ gvfs-trash / trash-cli / kioclient5 / kioclient
ELECTRON_OVERRIDE_DIST_PATH全让 electron 命令用本地构建的 Electron（自编译场景），替代 npm 下载的版本

三、开发 / 调试 / 日志

变量平台作用
ELECTRON_ENABLE_LOGGING全把 Chromium 内部日志打到控制台（等同 --enable-logging）
ELECTRON_LOG_FILE全Chromium 内部日志写入指定文件（等同 --log-file）
ELECTRON_ENABLE_STACK_DUMPING全崩溃时把堆栈打到控制台；crashReporter 启动后失效
ELECTRON_DEFAULT_ERROR_MODEWindows崩溃时显示 Windows 原生崩溃对话框；crashReporter 启动后失效
ELECTRON_DEBUG_NOTIFICATIONSmacOSNotification 生命周期详细日志（创建/显示/激活/回复）
ELECTRON_DEBUG_MSIX_UPDATERWindowsMSIX 更新流程详细日志
ELECTRON_LOG_ASAR_READS全记录 ASAR 读取的偏移与路径到系统 tmpdir，用于优化打包文件排序

四、安全警告开关（非官方清单，但常用）

变量作用
ELECTRON_ENABLE_SECURITY_WARNINGS强制开启控制台安全警告（默认仅未打包的 electron 二进制显示）
ELECTRON_DISABLE_SECURITY_WARNINGS强制关闭（打包后的应用也会显示警告时用于压制）

来源：安全文档「Electron 安全警告」节，可设在 process.env 或 window 上。

国内环境典型组合

开发机（.npmrc + shell 二选一，.npmrc 团队共享更好）：

# .npmrc
electron_mirror=https://npmmirror.com/mirrors/electron/
electron_builder_binaries_mirror=https://npmmirror.com/mirrors/electron-builder-binaries/

# 或 shell 直接给（不经 npm 时，如手动跑 install.js / electron .）
export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

企业内网证书 + 代理：

export NODE_EXTRA_CA_CERTS=/path/to/corp-ca.pem
export ELECTRON_GET_USE_PROXY=true   # 走 HTTPS_PROXY 下载二进制

相关

关系图谱

反向链接