Ресурсы

Пользователи могут включить ресурсы, добавив в конфигурацию словарь «ключ — путь» в качестве поля assets. Во время сборки Node.js прочитает ресурсы по указанным путям и объединит их в подготовительный блоб. В созданном исполняемом файле пользователи могут получить ресурсы с помощью API sea.getAsset() и sea.getAssetAsBlob().

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "assets": {
    "a.jpg": "/path/to/a.jpg",
    "b.txt": "/path/to/b.txt"
  }
} copy

Приложение в виде единого исполняемого файла может получить доступ к ресурсам следующим образом:

const { getAsset, getAssetAsBlob, getRawAsset, getAssetKeys } = require('node:sea');
// Get all asset keys.
const keys = getAssetKeys();
console.log(keys); // ['a.jpg', 'b.txt']
// Returns a copy of the data in an ArrayBuffer.
const image = getAsset('a.jpg');
// Returns a string decoded from the asset as UTF8.
const text = getAsset('b.txt', 'utf8');
// Returns a Blob containing the asset.
const blob = getAssetAsBlob('a.jpg');
// Returns an ArrayBuffer containing the raw asset without copying.
const raw = getRawAsset('a.jpg'); copy

Дополнительную информацию см. в документации по API sea.getAsset(), sea.getAssetAsBlob(), sea.getRawAsset() и sea.getAssetKeys().

Поддержка снимка при запуске

Поле useSnapshot можно использовать для включения поддержки снимка при запуске. В этом случае скрипт main не будет выполняться при запуске конечного исполняемого файла. Вместо этого он будет выполнен на машине сборки при создании подготовительного блоба приложения в виде единого исполняемого файла. В созданный подготовительный блоб будет включён снимок, сохраняющий состояние, инициализированное скриптом main. Конечный исполняемый файл со внедрённым подготовительным блобом десериализует снимок во время выполнения.

Если useSnapshot имеет значение true, основной скрипт должен вызвать API v8.startupSnapshot.setDeserializeMainFunction(), чтобы настроить код, который должен выполняться при запуске конечного исполняемого файла пользователями.

Типичный способ использования снимка в приложении в виде единого исполняемого файла:

1. Во время сборки на машине сборки запускается основной скрипт, чтобы инициализировать кучу до состояния, готового к приёму пользовательского ввода. Скрипт также должен настроить главную функцию с помощью v8.startupSnapshot.setDeserializeMainFunction(). Эта функция будет скомпилирована и сериализована в снимок, но не будет вызвана во время сборки.
2. Во время выполнения главная функция запустится поверх десериализованной кучи на машине пользователя, чтобы обработать пользовательский ввод и сформировать результат.

Общие ограничения для скриптов снимка при запуске также применяются к основному скрипту, когда он используется для создания снимка приложения в виде единого исполняемого файла. Для адаптации к этим ограничениям основной скрипт может использовать API v8.startupSnapshot. См. документацию о поддержке снимка при запуске в Node.js.

Поддержка кэша кода V8

Если в конфигурации для useCodeCache задано значение true, при создании подготовительного блоба приложения в виде единого исполняемого файла Node.js скомпилирует скрипт main для создания кэша кода V8. Созданный кэш кода станет частью подготовительного блоба и будет внедрён в конечный исполняемый файл. При запуске приложения в виде единого исполняемого файла Node.js будет использовать кэш кода, чтобы ускорить компиляцию скрипта main, вместо того чтобы компилировать его с нуля, а затем выполнит скрипт, что позволит ускорить запуск.

Примечание: import() не работает, если useCodeCache имеет значение true.

Аргументы выполнения

Поле execArgv можно использовать для указания аргументов, специфичных для Node.js, которые будут автоматически применяться при запуске приложения в виде единого исполняемого файла. Это позволяет разработчикам приложений настраивать параметры среды выполнения Node.js, не требуя от конечных пользователей знания этих флагов.

Например, следующая конфигурация:

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "execArgv": ["--no-warnings", "--max-old-space-size=2048"]
} copy

укажет запускать SEA с флагами --no-warnings и --max-old-space-size=2048. В скриптах, встроенных в исполняемый файл, к этим флагам можно получить доступ с помощью свойства process.execArgv:

// If the executable is launched with `sea user-arg1 user-arg2`
console.log(process.execArgv);
// Prints: ['--no-warnings', '--max-old-space-size=2048']
console.log(process.argv);
// Prints ['/path/to/sea', 'path/to/sea', 'user-arg1', 'user-arg2'] copy

Аргументы, переданные пользователем, находятся в массиве process.argv начиная с индекса 2, как и при запуске приложения следующей командой:

node --no-warnings --max-old-space-size=2048 /path/to/bundled/script.js user-arg1 user-arg2 copy

Расширение аргументов выполнения

Поле execArgvExtension определяет, как можно передавать дополнительные аргументы выполнения помимо указанных в поле execArgv. Оно принимает одно из трёх строковых значений:

• "none": расширение не допускается. Будут использоваться только аргументы, указанные в execArgv, а переменная среды NODE_OPTIONS будет игнорироваться.
• "env": (по умолчанию) переменная среды NODE_OPTIONS может расширять список аргументов выполнения. Это поведение используется по умолчанию для обеспечения обратной совместимости.
• "cli": исполняемый файл можно запускать с --node-options="--flag1 --flag2", и эти флаги будут разобраны как аргументы выполнения Node.js, а не переданы пользовательскому скрипту. Это позволяет использовать аргументы, которые не поддерживаются переменной среды NODE_OPTIONS.

Например, при значении "execArgvExtension": "cli":

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "execArgv": ["--no-warnings"],
  "execArgvExtension": "cli"
} copy

Исполняемый файл можно запустить так:

./my-sea --node-options="--trace-exit" user-arg1 user-arg2 copy

Это будет эквивалентно выполнению следующей команды:

node --no-warnings --trace-exit /path/to/bundled/script.js user-arg1 user-arg2 copy

API приложения в виде единого исполняемого файла

Встроенный модуль node:sea позволяет взаимодействовать с приложением в виде единого исполняемого файла из основного скрипта JavaScript, встроенного в исполняемый файл.

sea.getAsset(key[, encoding])

Этот метод можно использовать для получения ресурсов, настроенных для включения в приложение в виде единого исполняемого файла во время сборки. Если соответствующий ресурс не найден, возникает ошибка.

• key <string> ключ ресурса в словаре, указанном в поле assets конфигурации приложения в виде единого исполняемого файла.
• encoding <string> Если этот параметр указан, ресурс будет декодирован как строка. Принимается любая кодировка, поддерживаемая TextDecoder. Если параметр не указан, вместо этого будет возвращён ArrayBuffer, содержащий копию ресурса.
• Возвращает: <string> | <ArrayBuffer>

sea.getAssetAsBlob(key[, options])

Похож на sea.getAsset(), но возвращает результат в виде <Blob>. Если соответствующий ресурс не найден, возникает ошибка.

• key <string> ключ ресурса в словаре, указанном в поле assets конфигурации приложения в виде единого исполняемого файла.
• options <Object>
  • type <string> Необязательный MIME-тип для блоба.
• Возвращает: <Blob>

sea.getRawAsset(key)

Этот метод можно использовать для получения ресурсов, настроенных для включения в приложение в виде единого исполняемого файла во время сборки. Если соответствующий ресурс не найден, возникает ошибка.

В отличие от sea.getAsset() или sea.getAssetAsBlob(), этот метод не возвращает копию. Вместо этого он возвращает исходный ресурс, встроенный в исполняемый файл.

Пока что пользователям следует избегать записи в возвращённый буфер массива. Если внедрённая секция не помечена как доступная для записи или выровнена неправильно, запись в возвращённый буфер массива может привести к аварийному завершению работы.

• key <string> ключ ресурса в словаре, указанном в поле assets конфигурации приложения в виде единого исполняемого файла.
• Возвращает: <ArrayBuffer>

sea.getAssetKeys()

• Возвращает <string[]> Массив, содержащий все ключи ресурсов, встроенных в исполняемый файл. Если ресурсы не встроены, возвращается пустой массив.

Этот метод можно использовать для получения массива всех ключей ресурсов, встроенных в приложение в виде единого исполняемого файла. Если метод вызван не внутри приложения в виде единого исполняемого файла, возникает ошибка.

require(id) во внедрённом основном скрипте не использует файловую систему

require() во внедрённом основном скрипте — это не то же самое, что require(), доступный модулям, которые не были внедрены. У него также нет свойств, которыми обладает невнедрённый require(), за исключением require.main. Его можно использовать только для загрузки встроенных модулей. Попытка загрузить модуль, доступный только в файловой системе, вызовет ошибку.

Вместо того чтобы полагаться на файловый require(), пользователи могут объединить приложение в отдельный файл JavaScript и внедрить его в исполняемый файл. Это также обеспечивает более детерминированный граф зависимостей.

Однако, если файловый require() всё же необходим, этого также можно добиться:

const { createRequire } = require('node:module');
require = createRequire(__filename); copy

__filename и module.filename во внедрённом основном скрипте

Значения __filename и module.filename во внедрённом основном скрипте равны process.execPath.

__dirname во внедрённом основном скрипте

Значение __dirname во внедрённом основном скрипте равно имени каталога для process.execPath.

Процесс создания приложения в виде единого исполняемого файла

Инструмент, предназначенный для создания приложения Node.js в виде единого исполняемого файла, должен внедрить содержимое блоба, подготовленного с помощью --experimental-sea-config", в:

• ресурс с именем NODE_SEA_BLOB, если двоичный файл node является файлом PE
• секцию с именем NODE_SEA_BLOB в сегменте NODE_SEA, если двоичный файл node является файлом Mach-O
• заметку с именем NODE_SEA_BLOB, если двоичный файл node является файлом ELF

Найдите в двоичном файле строку NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2:0 предохранителя и замените последний символ на 1, чтобы указать, что ресурс был внедрён.

Поддержка платформ

Поддержка приложений в виде единого исполняемого файла регулярно тестируется в CI только на следующих платформах:

• Windows
• macOS
• Linux (все дистрибутивы, поддерживаемые Node.js, кроме Alpine, и все архитектуры, поддерживаемые Node.js, кроме s390x)

Это связано с отсутствием более подходящих инструментов для создания приложений в виде единого исполняемого файла, которые можно было бы использовать для тестирования этой функции на других платформах.

Мы будем рады предложениям по другим инструментам и рабочим процессам для внедрения ресурсов. Чтобы помочь нам задокументировать их, начните обсуждение на странице https://github.com/nodejs/single-executable/discussions.