Ресурсы

Пользователи могут включить ресурсы, добавив в конфигурацию словарь «ключ — путь» в поле assets. Во время сборки Node.js считывает ресурсы по указанным путям и объединяет их в подготовительный blob. В созданном исполняемом файле пользователи могут получить ресурсы с помощью 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 не будет выполняться при запуске итогового исполняемого файла. Вместо этого он будет выполнен при создании подготовительного blob однофайлового исполняемого приложения на машине сборки. Созданный подготовительный blob будет содержать снимок, фиксирующий состояния, инициализированные скриптом main. Итоговый исполняемый файл со внедренным подготовительным blob десериализует снимок во время выполнения.

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

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

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

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

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

Если в конфигурации для useCodeCache задано значение true, во время создания подготовительного blob однофайлового исполняемого приложения Node.js скомпилирует скрипт main для создания кэша кода V8. Созданный кэш кода станет частью подготовительного blob и будет внедрен в итоговый исполняемый файл. При запуске однофайлового исполняемого приложения 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.
• Возвращает: <Blob>

sea.getRawAsset(key)

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

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

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

• 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.

Использование нативных дополнений во внедренном главном скрипте

Нативные дополнения можно объединить в однофайловое исполняемое приложение как ресурсы, указав их в поле assets файла конфигурации, используемого для создания подготовительного blob однофайлового исполняемого приложения. Затем дополнение можно загрузить во внедренном главном скрипте, записав ресурс во временный файл и загрузив его с помощью process.dlopen().

{
  "main": "/path/to/bundled/script.js",
  "output": "/path/to/write/the/generated/blob.blob",
  "assets": {
    "myaddon.node": "/path/to/myaddon/build/Release/myaddon.node"
  }
} copy

// script.js
const fs = require('node:fs');
const os = require('node:os');
const path = require('node:path');
const { getRawAsset } = require('node:sea');
const addonPath = path.join(os.tmpdir(), 'myaddon.node');
fs.writeFileSync(addonPath, new Uint8Array(getRawAsset('myaddon.node')));
const myaddon = { exports: {} };
process.dlopen(myaddon, addonPath);
console.log(myaddon.exports);
fs.rmSync(addonPath); copy

Известная проблема: если однофайловое исполняемое приложение создано с помощью postject в контейнере Docker Linux arm64, созданный двоичный файл ELF не содержит правильную хеш-таблицу для загрузки дополнений и аварийно завершит работу при вызове process.dlopen(). Чтобы обойти эту проблему, создавайте однофайловое исполняемое приложение на других платформах или хотя бы в среде Linux arm64 вне контейнера.

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

Инструмент, предназначенный для создания однофайлового исполняемого приложения Node.js, должен внедрить содержимое blob, подготовленного с помощью --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.