Electron Forge Core 编程 API 指南：在 Node 环境中以代码驱动 Electron 应用打包、构建与发布

开发工具桌面应用前端构建【免费下载链接】forge:electron: A complete tool for building and publishing Electron applications项目地址https://gitcode.com/gh_mirrors/fo/forge点击查看免费下载electron-forge/core是 Electron Forge 的核心逻辑模块它将package打包、make生成安装包、start开发启动与release发布等能力封装为可直接在 Node.js 代码中调用的异步 API从而让你脱离 CLI 也能驱动完整的应用交付流水线。阅读本文后你将掌握api命名导出的全部方法及其选项含义、utils工具集与配置解析机制并能在此基础上编写自己的构建脚本或把 Forge 能力嵌入 CI 任务。模块定位CLI 背后的同一套核心逻辑electron-forge/core对应仓库中的 packages/api/core 目录其 package.json 将该包描述为A complete tool for building modern Electron applications是 Forge 各命令背后的共享实现层。CLI 命令见 packages/api/cli/src/electron-forge.ts——start、package、make、release与已隐藏的publish别名——最终都会落入本模块的 API 执行因此用代码调用这些方法与敲击命令行走的是同一条流水线只是入口不同。模块满足以下工程特征均可从源码确认纯 ESM 包package.json声明type: module导出入口为dist/api/index.js类型声明位于dist/api/index.d.tsNode 版本要求engines.node为 22.13.0CLI 入口在启动时也会用 semver 校验当前 Node 版本见 electron-forge.ts内部依赖基于electron/packager完成打包、listr2组织任务流水线、jiti加载 TypeScript 配置、electron-forge/tracer进行调用链追踪。基本用法一行代码打包当前目录核心文档给出的最小用法极其简洁——使用命名导出api传入应用目录即可import { api } from electron-forge/core; // 将当前目录打包为 Electron 应用 api.package(import.meta.dirname);import { api } from electron-forge/core; const dir /path/to/my-electron-app; const results await api.package({ dir });关于这段代码有几点需要结合源码说明api是一个预先实例化的单例对象。在 packages/api/core/src/api/index.ts 中ForgeAPI类被实例化为const api new ForgeAPI()并连同ForgeUtils实例utils、ForgeMakeResult、ForgePackageResult、ElectronProcess以及MakeOptions、PackageOptions、ReleaseOptions、StartOptions等类型一并导出。所有方法都是异步的返回 Promisepackage解析为ForgePackageResult[]make解析为ForgeMakeResult[]start解析为ElectronProcess一个承载着 Electron 子进程句柄的对象。用户侧配置依然来自 Forge 配置文件或 package.json 的config.forge字段API 只是提供在 Node 环境直接调用方法的能力并不会替代配置系统配置加载机制详见下文配置从哪来一节。ForgeAPI 方法全解五个核心操作ForgeAPI类共暴露五个方法见 packages/api/core/src/api/index.ts其中publish是release的废弃别名。下面逐一说明其选项与返回值选项字段均取自源码中的接口定义。package(opts)打包应用对应 package.ts 中的PackageOptions用于把应用打包为可分发目录内含 Electron 二进制返回ForgePackageResult[]选项类型说明dirstring要打包的应用目录默认process.cwd()interactiveboolean是否启用可视化交互渲染提示用户选择默认falsearchForgeArch目标架构默认当前主机架构来自electron/get的getHostArch()platformForgePlatform目标平台默认process.platformoutDirstring打包产物输出目录默认由 Forge 配置推导从实现看package的流水线会依次定位应用目录resolveDir、加载 Forge 配置getForgeConfig、读取经过配置变异后的 package.jsonreadMutatedPackageJson且强制要求存在main入口字段、执行generateAssets等打包钩子最后调用electron/packager的packager函数完成打包。make(opts)生成可分发的安装包对应 make.ts 中的MakeOptions在打包基础上继续调用各个 Maker如 DMG、Deb、MSI、Zip生成安装包返回ForgeMakeResult[]选项类型说明dirstring应用目录默认process.cwd()interactiveboolean是否可视化交互默认falsefromPackageboolean复用 out 目录中上一次package的产物直接生成安装包而不重新打包skipPackagebooleanfromPackage的废弃别名二者取其一生效overrideTargetsForgeConfigMaker[] \| string[]覆盖 forge 配置中的 makers 列表可传 Maker 名称字符串archForgeArch目标架构默认主机架构platformForgePlatform目标平台默认当前平台outDirstring分发产物输出目录值得注意的实现细节make每次运行都会把结果清单写入outDir下的make-results目录见下文make 结果清单这为 CI 场景下先构建、后发布的分离流程提供了基础。release(opts)发布应用对应 release.ts 中的ReleaseOptions是publish的新名publish会在未来主版本中移除负责把产物发布到目标服务返回Promisevoid选项类型说明dirstring应用目录默认process.cwd()interactiveboolean是否可视化交互默认falsepublishTargetsForgeConfigPublisher[] \| string[]发布目标默认取 forge 配置中的publishers可传名称覆盖makeOptionsMakeOptions透传给内部make()的选项对象outDirstring分发产物目录fromMakeboolean直接发布上一次make保存的清单产物而不重新打包构建适合 CI 各 Job 分离构建与发布dryRunboolean废弃选项只执行 package 与 make 步骤而不发布make现在总会保存结果等价于直接调用make()dryRunResumebooleanfromMake的废弃别名源码中还包含几组防御性校验dryRun与fromMake不能同时开启there would be nothing to dofromMake与fromPackage也不能组合因为前者本身已复用打包产物。start(opts)开发模式启动对应 start.ts 中的StartOptions启动 Electron 应用并返回ElectronProcess。它在飞行中替你完成原生模块重建native module rebuild其运行流程为定位应用 → 加载配置 → 通过listrCompatibleRebuildHook准备原生依赖 → 运行generateAssets与preStart钩子 → 定位 Electron 可执行文件并spawn子进程。可用的选项包括dir、appPath、interactive、enableLogging置为 true 时注入ELECTRON_ENABLE_LOGGING/ELECTRON_ENABLE_STACK_DUMPING环境变量、args、runAsNode注入ELECTRON_RUN_AS_NODE、inspect与inspectBrk注入--inspect/--inspect-brk。start还带有一套终端交互体验交互模式下通过electron-forge/multi-logger渲染多标签页 UI应用的 stdout/stderr 被接入名为App的标签页支持按r键或输入rs重启应用主进程重启逻辑会妥善处理kill → exit → respawn窗口期内的并发请求。若某个插件接管了启动逻辑pluginInterface.overrideStartLogic则按插件返回的结果可执行文件路径字符串、带前缀参数的数组或现成的子进程执行。ForgeUtils配置与动态值工具集api之外模块还导出了utils实例ForgeUtils见 packages/api/core/src/util/index.ts提供以下实用能力方法作用fromBuildIdentifier(map)创建按buildIdentifier动态取值的配置项如fromBuildIdentifier({ stable: App, beta: App Beta })getElectronVersion解析应用对应的 Electron 版本spawnPackageManager调用项目的包管理器执行命令registerForgeConfigForDirectory(dir, config)为指定目录注册一份虚拟Forge 配置优先级高于forge.config.js等真实文件unregisterForgeConfigForDirectory(dir)注销先前注册的虚拟配置其中fromBuildIdentifier返回一个带有__isMagicBuildIdentifierMap标记的对象最终解析后的配置会通过 Proxy 在读取时按buildIdentifier键名取出对应值见 forge-config.ts。配置从哪来解析顺序与动态值机制文档强调用户侧配置仍通过 forge 配置文件或 package.json 的config.forge完成其解析逻辑集中在 packages/api/core/src/util/forge-config.ts 的getForgeConfig(dir)中实际顺序为先查通过registerForgeConfigForDirectory注册的内存配置优先级最高否则读取package.json的config.forge字段若以上都没有或配置为字符串路径则按.js→.mjs→.cjs→.ts→.mts→.cts的顺序探测forge.config.*文件若配置文件指向.ts/.mts/.cts通过jiti加载其余扩展名走原生动态import配置既可以是一个静态对象也可以是异步函数() PromiseForgeConfig函数形态会被调用取返回值。解析后配置会与默认值rebuildConfig: {}、packagerConfig: {}、makers: []、publishers: []、plugins: []合并接着创建PluginInterface并执行resolveForgeConfig变异钩子最后通过proxify包装——该 Proxy 支持两套动态能力环境变量覆盖形如ELECTRON_FORGE_PACKAGER_CONFIG_*的环境变量可覆盖对应配置项键名转成大写蛇形构建标识取值配置中任何由fromBuildIdentifier创建的值都会按当前buildIdentifier自动取对应分支。错误处理拒绝值不一定是 Error 对象核心文档特别提醒了错误处理契约所有方法返回 Promise因此你必须处理一切 rejection并且rejection 不总是Error实例——Forge 常见做法是直接用字符串拒绝 Promise。因此import { api } from electron-forge/core; try { await api.package({ dir: /path/to/app }); } catch (err) { // err 可能是字符串而非 Error不要假设 stack / message 一定存在 if (typeof err string) { console.error(Forge rejected with string:, err); } else if (err typeof err object message in err) { console.error(Forge rejected with error:, err.message); } else { console.error(Forge rejected with:, err); } }编写包装脚本时不要依赖err.stack或err.message的存在应同时兼容字符串、对象与未知类型并在日志中输出原始值便于排查。深入机制任务流水线与 make 结果清单Listr 任务管线四个方法均基于listr2的Listr构建子任务流水线如Loading configuration、Running generateAssets hook、Publishing distributables等步骤并且遵循统一的渲染策略非交互模式interactive: false下采用静默渲染器避免污染脚本输出设置DEBUG环境变量或处于CI环境时回退为可读文本渲染器任务名与分类category: electron-forge/core通过electron-forge/tracer记录便于追踪调用链。make 结果清单make-results每次make运行都会在输出目录下生成make-results目录写入名为*.forge-make.json的结果清单见 make-results.ts。写入采用临时文件 rename的原子化策略避免进程中途退出留下半截文件读取时若清单损坏则静默跳过。release({ fromMake: true })会加载这些清单并校验所有产物文件真实存在然后按平台/架构分组逐批发布——这正是一次构建、多处发布CI 流水线的基础。实战场景示例场景一为 CI 编写打包 生成安装包脚本import { api } from electron-forge/core; const results await api.make({ dir: process.cwd(), interactive: false, // CI 下静默执行 platform: process.platform, // 默认值可显式指定 arch: process.arch, }); for (const result of results) { console.log([${result.maker}] ${result.artifacts.join(, )}); }场景二分离构建与发布复用先前 make 结果import { api } from electron-forge/core; // Job A仅构建 await api.make({ dir: projectDir, interactive: false }); // Job B仅发布复用 Job A 的产物 await api.release({ dir: projectDir, interactive: false, fromMake: true, publishTargets: [electron-forge/publisher-github], });场景三以代码驱动开发启动并接管重启import { api } from electron-forge/core; const proc await api.start({ dir: projectDir, interactive: true, enableLogging: true, inspect: true, // 附加 --inspect便于调试主进程 }); proc.on(exit, () console.log(app exited));与 CLI 的关系及适用边界CLI 命令electron-forge.ts与核心 API 共享同一套底层实现CLI 在每次子命令前还会先执行Checking your system系统检查而直接调用 API 时这些外围检查由你自行决定是否需要。本模块提供的是Node 环境中的方法调用配置仍然以文件或 package.json 字段为准且不会改变 Forge 的配置加载语义。所有方法默认以process.cwd()为应用目录传入dir时请确保该目录是包含package.json含main入口start还要求version字段的合法 Electron 应用目录。综合来看electron-forge/core是理解 Electron Forge 内部机制的一把钥匙它既承载了从打包到发布的全链路逻辑又以极简的api/utils双导出形态把复杂流水线暴露为可编程接口非常适合作为自定义构建工具链与自动化发布流程的集成点。若需要查阅每个方法的完整类型签名可在构建后查看dist/api/index.d.ts或对应方法的源码注释如 index.ts 中的 JSDoc。赞分享开发工具桌面应用前端构建【免费下载链接】forge:electron: A complete tool for building and publishing Electron applications项目地址https://gitcode.com/gh_mirrors/fo/forge点击查看免费下载相关推荐Electron Forge 完全指南一站式构建与发布 Electron 应用Electron Forge 完全指南一站式构建与发布 Electron 应用 Electron Forge 是一个将 Electron 应用的创建、打包、安开发工具桌面应用前端构建Electron 应用打包与分发完整指南用 Electron Forge 从源码到安装包Electron 应用打包与分发完整指南用 Electron Forge 从源码到安装包 当你已经用 Electron 完成了一个能在开发模式下正常运行的应用桌面应用跨平台前端使用 Electron Forge 的 MSIX Maker 构建 Windows 应用包配置、代码签名与发布指南使用 Electron Forge 的 MSIX Maker 构建 Windows 应用包配置、代码签名与发布指南 本文围绕 Electron Forge 官开发工具桌面应用前端构建上一篇BabelDOC完整指南3步掌握专业PDF文档智能翻译下一篇yewtube终极URL解析指南如何直接播放任意网络视频链接创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考