ASAR Archives
在完成应用程序打包后,应用的源代码通常被打包成一个 ASAR 归档文件,这是为 Electron 应用设计的一种简单的扩展归档文件格式。通过打包应用,我们可以缓解 Windows 上长路径名称的问题,加速 require 并隐藏你的源代码以避免能够轻易查看。
打包后的应用运行在一个虚拟文件系统并且大多数API都可以正常执行, 但有些时候你可能在某种情况下需要在 ASAR 压缩文件内执行.
使用 ASAR 包
Electron 有两套 API:Node API 和 Web API 分别由 Node.js 和 Chromium 提供。两套 API 都支持都支持从 ASAR 包内读取文件.
Node API
由于 Electron 的特殊补丁程序, Node API 比如 fs.readFile 和 require 使用 ASAR 就像是使用虚拟目录一样, 里面的文件也像是在文件系统内一样.
例如,假设我们在 /path/to 文件夹下有个 example.asar 包:
$ asar list /path/to/example.asar
/app.js
/file.txt
/dir/module.js
/static/index.html
/static/main.css
/static/jquery.min.js
在 ASAR 归档中读取文件:
const fs = require('node:fs')
fs.readFileSync('/path/to/example.asar/file.txt')
列出档案根目录下的所有文件:
const fs = require('node:fs')
fs.readdirSync('/path/to/example.asar')
使用档案中的模块:
require('./path/to/example.asar/dir/module.js')
Directories in an archive can also be iterated with fs.opendir, and symbolic links stored in an archive can be inspected with fs.readlink, which returns the link's target relative to the link, like a real filesystem would.
你也可以在 ASAR 存档内使用 BrowserWindow 来显示一个网络页面:
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.loadURL('file:///path/to/example.asar/static/index.html')
Web API
在网页中,可以使用 file: 协议请求归档中的文件。就像是 Node API, ASAR 存档可以被作为目录处理.
例如,用 $.get 获取文件:
<script>
let $ = require('./jquery.min.js')
$.get('file:///path/to/example.asar/file.txt', (data) => {
console.log(data)
})
</script>
将 ASAR 归档文件看作是一个普通文件
某些情况下比如对 ASAR 归档文件进行校验,我们需要像读取 “文件” 那样读取 ASAR 文件。为此你可以使用内置的没有asar功能的和原始fs模块一模一样的original-fs模块。
const originalFs = require('original-fs')
originalFs.readFileSync('/path/to/example.asar')
您也可以将 process.noAsar 设置为 true 以禁用 fs 模块中对 asar 的支持:
const fs = require('node:fs')
process.noAsar = true
fs.readFileSync('/path/to/example.asar')
Node API 的局限性
尽管我们已经尽了最大努力使得 ASAR 文件使用 Node API 时的应用尽可能的趋向于真实的目录结构,但仍有一些底层 Node API 我们无法保证其正常工作。
档案文件是只读的
归档文件中的内容不可更改,所以 Node APIs 里那些会修改文件的方法在使用 ASAR 文件时都无法正常工作.
工作目录不能设置为档案文件里的目录
尽管ASAR档案被视为目录,但实际上文件系统中并不存在真正的目录,因此无法将工作目录设置为ASAR档案中的目录。将 asar 中的文件夹以 cwd 形式作为参数传入一些 API 中也会报错。
File Descriptors for Files in Archives
fs.open, fs.openSync and fs.promises.open return real file descriptors (and FileHandles) for files in ASAR archives, backed by the archive itself, so APIs built on top of them - fs.read, fs.readv, fs.fstat, fs.readFile(fd), fs.createReadStream, FileHandle#readFile, FileHandle#createReadStream, and so on - read directly out of the archive without any temporary copy. Likewise fs.copyFile, fs.cp and their sync and promise variants copy straight from the archive to the destination.
Because archives are read-only, opening a file inside an archive with any flag that allows writing (w, a, r+, ...) fails with EACCES, and fs.fchmod, fs.fchown and fs.futimes on such a descriptor fail with EACCES too. The descriptor only identifies the entry to Node's fs module; it is not backed by the file's contents, so passing it to code outside of fs (for example a native addon that reads from the raw descriptor, child_process stdio, net.Socket({ fd }) or http2stream.respondWithFile()) fails with EBADF and is not supported.
某些 API 需要额外解压档案包
For APIs that rely on passing the real file path to underlying system calls, Electron will extract the needed file into a temporary file and pass the path of the temporary file to the APIs to make them work. This adds a little overhead for those APIs.
需要额外解压的 API 有:
child_process.execFilechild_process.execFileSyncprocess.dlopen- 用在require原生模块时
fs.stat 的不真实统计信息
对 asar 档案中的文件取 fs.stat,返回的 Stats 对象不是精确值,因为这些文件不是真实存在于文件系统里。所以除了文件大小和文件类型以外,你不应该依赖 Stats 对象的值。
执行 ASAR 档案中的二进制文件
有一些Node API可以执行二进制文件,例如child_process.exec、child_process.spawn和child_process.execFile,但只有execFile支持在ASAR档案内执行二进制文件。
因为 exec 和 spawn 允许 command 替代 file 作为输入,而 command 是需要在 shell 下执行的. 目前没有 可靠的方法来判断 command 中是否在操作一个 asar 包中的文件,而且即便可以判断,我们依旧无法保证可以在无任何 副作用的情况下替换 command 中的文件路径。
向 ASAR 档案添加未打包的文件
如上所述,某些 Node API 被调用时会解压文件到文件系统。除了性能问题外,可能会触犯各种防病毒扫描程序。
你可以把使用--unpack 选项作为将各种文件保持为非压缩状态的一种解决方法。在下面的示例中,原生Node.js模块的共享库将不会被打包:
$ asar pack app app.asar --unpack *.node
运行命令后,您将会看到 app.asar.unpacked 文件夹与 app.asar 文件一起被创建了。没有被打包的文件和 app.asar 会一起存档发布。