ASAR官网介绍： https://www.electronjs.org/zh/docs/latest/tutorial/asar-archives
ASAR是一个由 Electron 官方维护、基于 Node.js 的命令行工具/模块，用来把「一堆小文件」归档成「一个 .asar 文件」，从而解决 Windows 长路径、文件数量、首次读取性能等问题。
一、安装
- 全局安装（推荐在 CI / 开发机用）
npminstall-g @electron/asar# 全局命令 asar 可用asar -V# 验证，返回版本号即成功，注意V需要大写- 项目内安装（推荐在脚本里调用 API）
npminstall-D @electron/asar# 本地 devDependencynpx asar …# 直接用，无需全局二、命令行常用操作
- 打包
asar pack<源目录><输出.asar>例：asar pack ./dist app.asar- 解包
asar extract<xxx.asar><输出目录>例：asar extract app.asar ./unpacked- 仅查看目录结构
asar list app.asar- 排除大文件 / 原生模块（–unpack）
asar pack.app.asar –unpack “*.node” 结果同时生成 app.asar# 归档部分app.asar.unpacked/# 被排除的文件，运行时需并列放置三、在 Node 代码里调用 API
官方包 @electron/asar 暴露的接口极少，最常用的 3 个：
constasar=require('@electron/asar');// 1. 打包awaitasar.createPackage(srcDir,outputAsar);// 2. 解包awaitasar.extractAll(inputAsar,outDir);// 3. 读取单文件（不落地磁盘）constbuf=awaitasar.extractFile(inputAsar,'package.json');console.log(JSON.parse(buf.toString()));四、进阶技巧
- Electron 项目一体化
在 package.json 里加一行脚本，一键生成 app.asar：
"scripts":{"build:asar":"asar pack ./dist ./release/app.asar --unpack '*.node'"}VSCode 插件优化
把 node_modules 打成 node_modules.asar 可减少 30 % 文件数；
配合 .vscodeignore 忽略原 node_modules 即可 。体积瘦身
先 npm install --production 去掉 devDeps，再 asar pack；
或者 –unpack-dir “{@types,ts-node}” 排除开发时依赖 。加密 / 加固
asar 本身只提供“打包”而非“加密”。如需防篡改，可：
• 在 Electron 主进程里对 asar 做完整性校验（sha256）；
• 或者改用 electron-builder 的 “asarUnpack” + “afterPack” 钩子做自定义加密 。
五、ASAR的局限性
只读、不可热更新
ASAR 一旦生成就是只读镜像，运行时无法往里写日志、改配置。
社区有人尝试“解压→patch→重打包”做增量更新，官方明确表态「低效但可行」，不会提供原生增量 API。工作目录（cwd）无法指向包内路径
任何把 cwd 设成 asar 内目录的代码（如 spawn 选项、某些 C++ addon）都会直接抛 ENOENT。部分 Node API 必须先解压到临时目录
底层需要“真实文件路径”的系统调用，Electron 会在后台把文件拷到 %TEMP%/.com.github.Electron.xxx/ 再执行：- child_process.execFile / execFileSync
- fs.open / openSync
- process.dlopen（require 原生模块时）
结果：
- 首次调用变慢；
- 临时文件不自动清理，长期运行会堆积；
- 若杀进程会留下僵尸文件。
fs.stat 返回“假”信息
除了 size、isFile/Directory 外，mtime/uid 等全为 0，依赖精确时间的日志切割、缓存校验会翻车。原生模块必须 --unpack
.node 文件如果留在包内，require 时会被解包到临时目录，但部分杀毒软件会把“可执行体突然落地”当成可疑行为拦截；
正确姿势是打包时加 --unpack “*.node”，让 xxx.asar.unpacked 与 xxx.asar 并列分发。单文件体积上限 ≈ 4 GB
ASAR 索引用 32-bit 偏移，理论极限 4 GB；electron-builder 在 ≥4.2 GB 直接报错中断。
视频、3D 纹理等大资源应放到 extraFiles 走外部分包。无加密、源码裸奔
ASAR 只是 tar-like 格式，用十六进制编辑器就能直接看到源码。
社区有“asar 加密补丁”，但限制极多：- 只能加密 JS，JSON/图片明文依旧；
- 必须开 nodeIntegration，preload 脚本失效；
- 动态 import()、HTML
<script src>全部失效； - 需要自行编译 C++ 扩展，密钥埋 binary，仍可被逆向。
官方立场：要真保密就改 Electron 源码重新编译，否则接受“只能防君子”。
调试阶段效率低
开发时想改一行代码也要重新 asar pack，否则热重载看不到；
VSCode、webpack 这类工具链需要额外脚本把 asar 解包到内存或临时目录，调试体验比直接文件夹差。
六、开启ASAR注意点
必须改（否则运行时报错）：
不要把工作目录（cwd）指到包内
所有child_process.spawn / exec的cwd选项、process.chdir()都只能指向真实磁盘目录。
asar 内部路径在系统调用层不存在，会立即抛ENOENT。不要把原生模块（.node）/可执行二进制留在包内
require('xxx.node')或execFile('ffmpeg')时，Electron 会偷偷把文件解包到%TEMP%再运行；
但部分杀毒软件会拦截“落地可执行体”，正确姿势是打包时加asar pack . app.asar --unpack "*.node" --unpack "bin/*"
让app.asar.unpacked与app.asar并列分发。不要依赖
fs.stat的mtime / uid / mode
asar 只提供size与isFile/Directory，其余字段全是 0；
日志按时间切分、缓存按时间戳比对等逻辑会翻车。不要对包内文件做写操作
asar 是只读镜像，fs.writeFile / fs.appendFile / fs.rename都会直接抛EROFS；
配置文件、日志、下载内容必须写到app.getPath('userData')等真实目录。
强烈建议改（否则首次调用变慢或调试困难）：
不要
fs.readFileSync超大文本到 Renderer
首次读取会整包解包到内存，>100 MB 的 JSON 会卡 UI；
大资源放extraResources走外部分包，或按需流式读取。不要把动态 import()的路径写成运行时拼接
如import('./lang/'+lang+'.js')，webpack 会无法提前分析依赖，
导致对应文件被打包器漏拷，运行时报Cannot find module。
改成显式 map 或require.context让构建工具可静态分析。不要把__dirname / __filename当真实磁盘路径再二次运算
在 asar 里它们返回的是虚拟路径，
若再path.join(__dirname, '../assets')后传给原生库，会拿到不存在的路径。
需要真实路径时，用app.isPackaged判断后走app.getAppPath()或process.resourcesPath。
