跳转到主内容

ASAR Archives

在完成应用程序分布后，应用程序的源代码通常会被绑定到ASAR存档中，这是一种为 Electron 应用程序而设计的简易存档格式。通过捆绑到应用程序中，我们可以缓解 Windows 上加载长路径名称的问题，加速加载并隐藏你的源码, 避免粗略的检查。 By bundling the app we can mitigate issues around long path names on Windows, speed up require and conceal your source code from cursory inspection.

The bundled app runs in a virtual file system and most APIs would just work normally, but for some cases you might want to work on ASAR archives explicitly due to a few caveats.

使用 asar 包​

Electron 有两套 API：Node API 和 Web API 分别由 Node.js 和 Chromium 提供。 Both APIs support reading files from ASAR archives.

Node API​

With special patches in Electron, Node APIs like fs.readFile and require treat ASAR archives as virtual directories, and the files in it as normal files in the filesystem.

例如，假设我们在 /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('fs')
fs.readFileSync('/path/to/example.asar/file.txt')

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

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

使用档案中的模块：

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

You can also display a web page in an ASAR archive with BrowserWindow:

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('file:///path/to/example.asar/static/index.html')

Web API​

在网页中，可以使用 file: 协议请求归档中的文件。 Like the Node API, ASAR archives are treated as directories.

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

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

Treating an ASAR archive as a Normal File​

For some cases like verifying the ASAR archive's checksum, we need to read the content of an ASAR archive as a file. 为此你可以使用内置的没有asar功能的和原始fs模块一模一样的original-fs模块。

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

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

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

Node API 的局限性​

Even though we tried hard to make ASAR archives in the Node API work like directories as much as possible, there are still limitations due to the low-level nature of the Node API.

档案文件是只读的​

The archives can not be modified so all Node APIs that can modify files will not work with ASAR archives.

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

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 对象的值。

Executing Binaries Inside ASAR archive​

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 中的文件路径。

Adding Unpacked Files to ASAR archives​

如上所述，某些 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:

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

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