ASAR Archives

在完成应用程序分布后，应用程序的源代码通常会被绑定到ASAR存档中，这是一种为 Electron 应用程序而设计的简易存档格式。通过捆绑到应用程序中，我们可以缓解 Windows 上加载长路径名称的问题，加速加载并隐藏你的源码, 避免粗略的检查。 通过捆绑到应用程序中，我们可以缓解 Windows 上加载长路径名称的问题，加速加载并隐藏你的源码, 避免粗略的检查。

打包后的应用运行在一个虚拟文件系统并且大多数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 包：

  1. $ asar list /path/to/example.asar
  2. /app.js
  3. /file.txt
  4. /dir/module.js
  5. /static/index.html
  6. /static/main.css
  7. /static/jquery.min.js

在 ASAR 归档中读取文件：

  1. const fs = require('fs')
  2. fs.readFileSync('/path/to/example.asar/file.txt')

列出档案根目录下的所有文件：

  1. const fs = require('fs')
  2. fs.readdirSync('/path/to/example.asar')

使用档案中的模块：

  1. require('./path/to/example.asar/dir/module.js')

你也可以在 ASAR 存档内使用 BrowserWindow 来显示一个网络页面:

  1. const { BrowserWindow } = require('electron')
  2. const win = new BrowserWindow()
  4. win.loadURL('file:///path/to/example.asar/static/index.html')

Web API

在网页中，可以使用 file: 协议请求归档中的文件。 就像是 Node API, ASAR 存档可以被作为目录处理.

例如，用 $.get 获取文件:

  1. <script>
  2. let $ = require('./jquery.min.js')
  3. $.get('file:///path/to/example.asar/file.txt', (data) => {
  4.   console.log(data)
  5. })
  6. </script>

将 ASAR 归档文件看作是一个普通文件

某些情况下比如对 ASAR 归档文件进行校验，我们需要像读取 “文件” 那样读取 ASAR 文件。 为此你可以使用内置的没有asar功能的和原始fs模块一模一样的original-fs模块。

  1. const originalFs = require('original-fs')
  2. originalFs.readFileSync('/path/to/example.asar')

您也可以将 process.noAsar 设置为 true 以禁用 fs 模块中对 asar 的支持：

  1. const fs = require('fs')
  2. process.noAsar = true
  3. fs.readFileSync('/path/to/example.asar')

Node API 的局限性

尽管我们已经尽了最大努力使得 ASAR 文件使用 Node API 时的应用尽可能的趋向于真实的目录结构，但仍有一些底层 Node API 我们无法保证其正常工作。

档案文件是只读的

归档文件中的内容不可更改，所以 Node APIs 里那些会修改文件的方法在使用 ASAR 文件时都无法正常工作.

工作目录不能设置为档案文件里的目录

Though ASAR archives are treated as directories, there are no actual directories in the filesystem, so you can never set the working directory to directories in ASAR archives. 将 asar 中的文件夹以 cwd 形式作为参数传入一些 API 中也会报错。

某些 API 需要额外解压档案包

Most fs APIs can read a file or get a file’s information from ASAR archives without unpacking, but for some 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. 对于这类API，会增加一些开销。

以下是一些需要额外解压的 API：

  • child_process.execFile
  • child_process.execFileSync
  • fs.open
  • fs.openSync
  • process.dlopen - 用在 require 原生模块时

fs.stat 的不真实统计信息

对 asar 档案中的文件取 fs.stat，返回的 Stats 对象不是精确值，因为这些文件不是真实存在于文件系统里。 所以除了文件大小和文件类型以外，你不应该依赖 Stats 对象的值。

执行 ASAR 档案中的二进制文件

There are Node APIs that can execute binaries like child_process.exec, child_process.spawn and child_process.execFile, but only execFile is supported to execute binaries inside ASAR archive.

因为 exec 和 spawn 允许 command 替代 file 作为输入，而 command 是需要在 shell 下执行的. 目前没有 可靠的方法来判断 command 中是否在操作一个 asar 包中的文件，而且即便可以判断，我们依旧无法保证可以在无任何 副作用的情况下替换 command 中的文件路径。

向 ASAR 档案添加未打包的文件

如上所述，某些 Node API 被调用时会解压文件到文件系统。 除了性能问题外，可能会触犯各种防病毒扫描程序。

As a workaround, you can leave various files unpacked using the --unpack option. In the following example, shared libraries of native Node.js modules will not be packed:

  1. $ asar pack app app.asar --unpack *.node

运行命令后，您将会看到 app.asar.unpacked 文件夹与 app.asar 文件一起被创建了。 没有被打包的文件和 app.asar 会一起存档发布。