跳到主要内容

ASAR 归档文件

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

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

使用 ASAR 归档文件

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

Node API

通过 Electron 中的特殊补丁,Node API(如 fs.readFilerequire)将 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 的伪造 Stat 信息

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

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

有一些 Node API 可以执行二进制文件,例如 child_process.execchild_process.spawnchild_process.execFile,但只有 execFile 支持执行 ASAR 归档文件中的二进制文件。

这是因为 execspawn 接受 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 归档文件一起发布。