Перейти к основному содержанию

ASAR Archives

After creating an application distribution, the app's source code are usually bundled into an ASAR archive, which is a simple extensive archive format designed for Electron apps. 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.

Using ASAR Archives​

In Electron there are two sets of APIs: Node APIs provided by Node.js and Web APIs provided by 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.

Например, предположим что у нас есть архив example.asar лежащий в /path/to:

$ asar list /path/to/example.asar
/app.js
/file.txt
/dir/module.js
/static/index.html
/static/main.css
/static/jquery.min.js

Read a file in the ASAR archive:

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')

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​

In a web page, files in an archive can be requested with the file: protocol. 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. Для этих целей вы можете использовать встроенный модуль original-fs, который предоставляет оригинальный интерфейс fs без поддержки обработки asar:

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

Также вы можете установить переменную process.noAsar в true для отключения поддержки asar в модуле fs:

const fs = require('node: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. Передача их в качестве опций 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.

Интерфейсы, которые требуют дополнительной распаковки:

  • child_process.execFile
  • child_process.execFileSync
  • fs.open
  • fs.openSync
  • process.dlopen - использует require на нативных модулях

Поддельная информация из fs.stat​

Объект Stats, возвращаемый fs.stat из asar архивов генерируется "с потолка", поскольку этих файлов нет в реальной файловой системе. Поэтому единственное, чему вы можете доверять в таком объекте 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. Нет надежного способа определить использует ли команда файл в asar-архиве и даже если мы это сделаем, то нет уверенности, можем ли мы заменить путь в команде без побочных эффектов.

Adding Unpacked Files to ASAR archives​

As stated above, some Node APIs will unpack the file to the filesystem when called. Apart from the performance issues, various anti-virus scanners might be triggered by this behavior.

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 была создана папка app.asar.unpacked. Она содержит незапакованные файлы и должна распространяться вместе с архивом app.asar.