[!info] related notes

• 所属 MOC: Build Tools MOC
• 相关概念: bundling-tools, commonjs-amd-umd, es6-module-import-export, vite-overview, webpack-build-process, Electron BrowserWindow, Electron preload 脚本
• 相关 MOC: Electron MOC, 前端工程化 MOC
• 易混淆概念: electron-project-issues, electron-native-compilation
• 发布链路: Electron Forge, Electron 代码签名与公证, Electron 自动更新

JavaScript 构建与 Electron 打包

范围

这篇笔记不讲单一工具配置，而是讲源码到可运行应用之间的链路：

• JS / TS 构建
• Electron 应用打包
• 安装包封装
• 运行时装载

为什么要拆层

很多问题看起来像“构建成功了但应用跑不起来”，本质是下面几层没有闭环：

• 源码层: TypeScript、JSX、ESM、别名路径、静态资源引用
• 构建层: 转译、模块解析、bundling、tree shaking、chunk 输出
• 打包层: asar、asarUnpacked、win-unpacked、安装包产物组织
• 运行层: Electron main / renderer / preload / worker / native module

JS 构建层

这一层负责把开发态源码变成可交付的 JS 产物。

• tsc / Babel / esbuild / SWC
• 静态依赖图分析
• CommonJS 与 ESM 兼容
• 资源与 chunk 的输出组织

Electron 打包层

这一层负责把构建产物整理成 Electron 应用。

• 主进程、渲染进程、preload 的产物分流
• asar 与 asarUnpacked
• electron-builder 或类似工具的产物布局
• 原生模块、worker、子进程脚本的真实文件可达性

运行时装载层

这一步决定程序启动后能不能真的把文件和模块找出来。

• require / import 的解析边界
• worker 路径和子进程路径
• 动态 require 和路径拼接
• 原生模块 ABI 和平台二进制
• db.waitForReady() 这类启动链路阻塞点

常见失配点

• 构建成功，但运行时找不到模块
• asar 里有文件，但 worker 需要真实路径
• main / renderer 的输出目录混在一起
• CommonJS / ESM 混用导致导出形态不一致
• 原生模块只按系统 Node 编译，没按 Electron 运行时重编

记忆方式

如果一个问题出现在“启动后”，先不要只盯着构建工具本身。

先问自己：

1. 产物在哪里
2. 运行时去哪找
3. 找到的是不是同一个模块形态
4. 需要真实文件还是归档文件
5. 是否跨了 Electron / Node / 浏览器边界

Related notes

• Build Tools MOC
• bundling-tools
• commonjs-amd-umd
• es6-module-import-export