跳转到主要内容

ASAR 归档

创建 应用程序分发包后，应用程序的源代码通常会捆绑到 ASAR 归档文件中，这是一种为 Electron 应用程序设计的简单扩展归档格式。 通过捆绑应用程序，我们可以缓解 Windows 上长路径名称的问题，加快 require 的速度，并防止您的源代码受到粗略检查。

捆绑的应用程序在虚拟文件系统中运行，并且大多数 API 都可以正常工作，但在某些情况下，由于一些注意事项，您可能需要显式地处理 ASAR 归档文件。

使用 ASAR 归档​

在 Electron 中，有两组 API：Node.js 提供的 Node API 和 Chromium 提供的 Web API。 这两种 API 都支持从 ASAR 归档文件中读取文件。

Node API​

通过 Electron 中的特殊补丁，像 fs.readFile 和 require 这样的 Node API 将 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')

您还可以使用 BrowserWindow 在 ASAR 归档文件中显示网页

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 归档文件的内容作为文件读取。 为此，您可以使用内置的 original-fs 模块，该模块提供没有 asar 支持的原始 fs API

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 的限制​

尽管我们尽了最大的努力使 Node API 中的 ASAR 归档文件尽可能像目录一样工作，但由于 Node API 的底层性质，仍然存在一些限制。

归档文件是只读的​

归档文件无法修改，因此所有可以修改文件的 Node API 都无法与 ASAR 归档文件一起使用。

工作目录不能设置为归档文件中的目录​

虽然 ASAR 归档文件被视为目录，但文件系统中没有实际的目录，因此您永远无法将工作目录设置为 ASAR 归档文件中的目录。 将它们作为某些 API 的 cwd 选项传递也会导致错误。

某些 API 上的额外解压缩​

大多数 fs API 可以在不解压缩的情况下从 ASAR 归档文件中读取文件或获取文件的信息，但对于某些依赖于将真实文件路径传递给底层系统调用的 API，Electron 会将所需的文件提取到临时文件中，并将临时文件的路径传递给 API，以使其工作。 这会为这些 API 增加一些开销。

需要额外解压缩的 API 是

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

fs.stat 的虚假状态信息​

fs.stat 及其在 asar 归档文件中的文件上返回的 Stats 对象是通过猜测生成的，因为这些文件不存在于文件系统中。 因此，除了获取文件大小和检查文件类型之外，您不应信任 Stats 对象。

执行 ASAR 归档文件中的二进制文件​

有一些 Node API 可以执行二进制文件，例如 child_process.exec、child_process.spawn 和 child_process.execFile，但只有 execFile 支持执行 ASAR 归档文件中的二进制文件。

这是因为 exec 和 spawn 接受 command 而不是 file 作为输入，并且 command 在 shell 下执行。 没有可靠的方法来确定命令是否使用 ASAR 归档文件中的文件，即使我们这样做，我们也不能确定是否可以在命令中替换路径而不会产生副作用。

将解压缩的文件添加到 ASAR 归档文件​

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

作为一种解决方法，您可以使用 --unpack 选项将各种文件保持解压缩状态。 在以下示例中，原生 Node.js 模块的共享库将不会被打包

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

运行命令后，您会注意到创建了一个名为 app.asar.unpacked 的文件夹以及 app.asar 文件。 它包含解压缩的文件，应与 app.asar 归档文件一起发布。