pkg

[!ВАЖНО]
pkg был отменен с выпуском 5.8.1 как последней версии. Уже существует множество успешных форков pkg с различными добавлениями функциональности. Кроме того, мы рады поддержке одиночных исполняемых приложений в Node.js 21 (одиночных исполняемых приложений). Спасибо за поддержку и вклады за все годы. Репозиторий останется открытым и архивированным.

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

Сценарии использования

• Создание коммерческой версии вашего приложения без исходного кода
• Создание демонстрационной/испытательной версии вашего приложения без исходного кода
• Быстрое создание исполняемых файлов для других платформ (перекомпиляция)
• Создание какого-либо типа самораспаковывающего архива или установщика
• Не требуется устанавливать Node.js и npm для запуска упакованного приложения
• Не требуется загружать сотни файлов через npm install для развертывания вашего приложения. Развертывание как одного файла
• Размещение ваших активов внутри исполняемого файла для повышения его переносимости
• Тестирование вашего приложения на новых версиях Node.js без установки## Использование

npm install -g pkg

После установки запустите pkg --help без аргументов, чтобы увидеть список опций:

pkg [options] <input>

  Опции:    -h, --help           выводит информацию о способе использования
             -v, --version        выводит версию pkg
             -t, --targets        запятая-разделенный список целей (см. примеры)
             -c, --config         package.json или любой json-файл с топ-уровневой конфигурацией
             --options            интегрирует v8 опции в исполняемый файл для запуска с ними
             -o, --output         имя выходного файла или шаблон для нескольких файлов
             --out-path           путь для сохранения выходного исполняемого файла или нескольких файлов
             -d, --debug          показывает больше информации во время процесса упаковки [выключен]
             -b, --build          не загружает предварительно скомпилированные базовые исполняемые файлы, а компилирует их
             --public             ускоряет процесс и раскрывает исходные файлы топ-уровневого проекта
             --public-packages    заставляет указанные пакеты считаться публичными
             --no-bytecode        пропускает генерацию байт-кода и включает исходные файлы как обычные js-файлы
             --no-native-build    пропускает сборку native-аддонов
             --no-signature       пропускает подпись окончательного исполняемого файла на macOS
             --no-dict            запятая-разделенный список имен пакетов для игнорирования словарей. Используйте --no-dict * для отключения всех словарей
             -C, --compress       [по умолчанию=None] алгоритм сжатия = Brotli или GZip
Примеры:
```  – Создает исполняемые файлы для Linux, macOS и Windows
    $ pkg index.js
  – Использует `package.json` из текущей рабочей директории и следует за значением 'bin'
    $ pkg .
  – Создает исполняемый файл для конкретной целевой машины
    $ pkg -t node16-win-arm64 index.js
  – Создает исполняемые файлы для целевых машин, выбранных вами
    $ pkg -t node16-linux,node18-linux,node16-win index.js
  – Включает `--expose-gc` и `--max-heap-size=34` в исполняемый файл
    $ pkg --options "expose-gc,max-heap-size=34" index.js
  – Считает пакетыA и пакетB публичными
    $ pkg --public-packages "packageA,packageB" index.js
  – Считает все пакеты публичными
    $ pkg --public-packages "*" index.js
  – Включает `--expose-gc` в исполняемый файл
    $ pkg --options expose-gc index.js
  – Уменьшает размер данных, упакованных внутри исполняемого файла, с помощью GZip
    $ pkg --compress GZip index.js

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

• Путь к файлу входа. Например, /path/app.js, тогда упакованный проект будет работать так же, как node /path/app.js
• Путь к package.json. Pkg будет следовать за значением bin в указанном package.json и использовать его как файл входа.
• Путь к директории. Pkg будет искать package.json в указанной директории. Смотрите выше.

Целевые машиныpkg может создавать исполняемые файлы для нескольких целевых машин одновременно. Вы можете указать запятой-разделенный список целевых машин через опцию --targets. Каноническая целевая машина состоит из 3 элементов, разделенных дефисами, например node18-macos-x64 или node14-linux-arm64.- nodeRange (node8), node10, node12, node14, node16 или latest

• платформа alpine, linux, linuxstatic, win, macos, (freebsd)
• архитектура x64, arm64, (armv6, armv7)

(элемент) не поддерживается, но вы можете попробовать скомпилировать самостоятельно.

Вы можете опустить любой элемент (и указать, например, только node14). Опущенные элементы будут взяты из текущей платформы или системного установки Node.js (его версии и архитектуры). Также есть псевдоним host, который означает, что все 3 элемента взяты из текущей платформы/Node.js. По умолчанию целевые машины являются linux,macos,win для текущей версии Node.js и архитектуры.

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

• Linux: настройте binfmt с помощью QEMU.
• macOS: возможно построение x64 на arm64 с помощью Rosetta 2, но не наоборот.
• Windows: возможно построение x64 на arm64 с помощью x64 эмуляции, но не наоборот.
• или, отключите генерацию байткода с помощью --no-bytecode --public-packages "*" --public.macos-arm64 является экспериментальным. Будьте осторожны с обязательным требованием к подписи кода. Финальный исполняемый файл должен быть подписан (достаточно временной подписи) с помощью codesign утилиты macOS (или ldid утилиты на Linux). В противном случае, исполняемый файл будет завершён ядром, и конечный пользователь не сможет разрешить его запуск. pkg пытается временно подписать финальный исполняемый файл. Если необходимо, вы можете заменить эту подпись своей собственной доверенной подписью Apple Developer ID.Чтобы иметь возможность генерировать исполняемые файлы для всех поддерживаемых архитектур и платформ, запустите pkg на хосте Linux с настроенным binfmt (QEMU эмуляцией) и установленным ldid.

Конфигурация

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

Однако ваш код может содержать вызовы require(variable) (так называемые нелитеральные аргументы к require) или использовать неjavascript файлы (например, представления, CSS, изображения и т.д.).

require('./build/' + cmd + '.js');
path.join(__dirname, 'views/' + viewName);

Такие случаи не обрабатываются pkg. Поэтому вы должны указать файлы - скрипты и активы - вручную в свойстве pkg вашего файла package.json.

  "pkg": {
    "scripts": "build/**/*.js",
    "assets": "views/**/*",
    "targets": [ "node14-linux-arm64" ],
    "outputPath": "dist"
  }

Пример выше включает все файлы в assets/ и каждый .js файл в build/, строит только для node14-linux-arm64, и размещает исполняемый файл внутри dist/.

Вы также можете указывать массивы шаблонов:

    "assets": [ "assets/**/*", "images/**/*" ]

Только убедитесь, что вы вызываете pkg package.json или pkg . для использования конфигурации файла package.json.### Скрипты scripts — это glob или список glob. Файлы, указанные как scripts, будут скомпилированы с помощью v8::ScriptCompiler и включены в исполняемый файл без исходных кодов. Они должны соответствовать стандартам JavaScript тех версий Node.js, которые вы указываете (см. Цели), то есть должны быть уже транспилированы.

Активыassets является glob

или списком glob. Файлы, указанные как assets, будут упакованы в исполняемый файл в качестве сырого содержимого без изменений. Файлы JavaScript также могут быть указаны как assets. Их исходный код не будет удаляться, что улучшает производительность выполнения файлов и упрощает отладку.

См. также Обнаружение активов в исходном коде и Снимок файловой системы.

Опции

Node.js-приложение может быть запущено с опциями времени выполнения (принадлежащими Node.js или V8). Чтобы вывести их список, введите node --help или node --v8-options.

Вы можете "запечь" эти опции времени выполнения в упакованное приложение. Приложение всегда будет запускаться с включенными опциями. Просто удалите -- из имени опции.

Вы можете указать несколько опций, объединив их в одну строку, разделенную запятой (,):

pkg app.js --options expose-gc
pkg app.js --options max_old_space_size=4096
pkg app.js --options max-old-space-size=1024,tls-min-v1.0,expose-gc

Выходные данные

Вы можете указать --output, если создаете только одно исполняемое приложение или --out-path, чтобы разместить исполняемые файлы для нескольких целей.

Отладка

Передайте --debug к pkg, чтобы получить лог процесса упаковки. Если у вас возникли проблемы с определенным файлом (кажется, не упакован в исполняемый файл), может быть полезно просмотреть лог.### Байткод (повторяемость)

По умолчанию, ваш исходный код предварительно компилируется в байткод V8 перед записью в выходной файл. Чтобы отключить эту функцию, передайте --no-bytecode к pkg.

Почему вы можете захотеть это сделать?

Если вам нужен повторяемый процесс сборки, где хэши вашего исполняемого файла (например, md5, sha1, sha256 и т.д.) имеют одинаковое значение между сборками. Поскольку компиляция байткода не является детерминированной (см. здесь или здесь), это результатирует в исполняемых файлах с различными хэшированными значениями. Отключение компиляции байткода позволяет одному и тому же входному файлу всегда иметь одинаковый выход.

Почему вы можете не захотеть это сделать?

Хотя компиляция в байткод не делает ваш исходный код 100% безопасным, она добавляет небольшой слой безопасности/приватности/неочевидности к вашему исходному коду. Отключение компиляции в байткод приводит к записи чистого исходного кода напрямую в исполняемый файл. Если вы на машине с операционной системой *nix и хотите пример, запустите pkg с флагом --no-bytecode, и используйте GNU strings для анализа выходных данных. Тогда вы сможете найти ваш исходный код с помощью grep.

Дополнительные соображенияУказание --no-bytecode завершится ошибкой, если в вашем проекте есть пакеты, которые не явно отмечены как публичные с помощью license в их package.json. По умолчанию, pkg проверяет лицензию каждого пакета и убеждается, что материалы, не предназначенные для публичного использования, будут включены только в виде байткода.

Если вам необходимо собрать pkg-бинарники для других архитектур и/или вы зависите от пакета с повреждённой license в его package.json, вы можете переопределить это поведение, явно добавив пакеты в белый список с помощью --public-packages "packageA,packageB" или установив все пакеты как публичные с помощью --public-packages "*".

Сборка

pkg имеет так называемые "базовые бинарники" — это на самом деле те же node исполняемые файлы, но с применёнными патчами. Они используются в качестве базы для каждого исполняемого файла, который создаёт pkg. pkg скачивает предварительно скомпилированные базовые бинарники перед упаковкой вашего приложения. Если вы предпочитаете компилировать базовые бинарники из исходного кода вместо загрузки их, вы можете передать опцию --build к pkg. Сначала убедитесь, что ваш компьютер соответствует требованиям для компиляции оригинального Node.js: BUILDING.md

Дополнительную информацию см. в pkg-fetch.### Сжатие

Передайте --compress Brotli или --compress GZip к pkg для дальнейшего сжатия содержимого файлов, хранящихся в исполняемом файле.

Эта опция может уменьшить размер встроенной файловой системы до 60%.

Время запуска приложения может быть немного уменьшено.

-C может быть использован как сокращение для --compress.

Окружение

Примеры

# Метод 1 - Использование export
export PKG_CACHE_PATH=/my/cache
pkg app.js

# Метод 2 - Передача аргументов перед скриптом
PKG_CACHE_PATH=/my/cache pkg app.js

Использование упакованного приложения

Командная строка вызова упакованного приложения ./app a b эквивалентна вызову node app.js a b

Снимок файловой системы

Во время процесса упаковки pkg собирает проектные файлы и помещает их в исполняемый файл. Это называется снимком. Время выполнения упакованное приложение имеет доступ к файловой системе снимка, где находятся все эти файлы.Упакованные файлы имеют префикс /snapshot/ в своих путях (или C:\snapshot\ в Windows). Если вы использовали командную строку pkg /path/app.js, то значение __filename в ходе выполнения будет вероятно /snapshot/path/app.js. Значение __dirname будет /snapshot/path также. Вот сравнительная таблица значений, связанных с путями:

Когда pkg встречает path.join(__dirname, '../path/to/asset'), он автоматически упаковывает указанный файл как актив. См. Активы. Обратите внимание, что path.join должен иметь два аргумента, и последний должен быть строковым литералом.

Таким образом, вы можете избежать создания конфигурации pkg для вашего проекта.

Native addons

Поддержка native addons (файлы .node) предусмотрена. Когда pkg встречает файл .node в вызове require, он упаковывает его как актив. В некоторых случаях (например, с использованием пакета bindings), путь к модулю генерируется динамически, и pkg не сможет его обнаружить. В этом случае вы должны добавить файл .node напрямую в поле assets в package.json.

Способ, которым Node.js требует native addon, отличается от обычного JS файла. Ему требуется наличие файла на диске для загрузки, но pkg генерирует только один файл. Чтобы обойти это, pkg создаёт временный файл на диске. Эти файлы остаются на диске после завершения процесса и используются снова при следующем запуске процесса.

Когда устанавливается пакет, содержащий native модуль, модуль компилируется против текущей системной версии Node.js. Затем, когда вы компилируете свой проект с помощью pkg, обратите внимание на опцию --target. Вы должны указать ту же версию Node.js, что и ваша системная, чтобы сделать скомпилированный исполняемый файл совместимым с файлами .node.Обратите внимание, что полностью статические бинарные файлы Node.js не способны загружать native bindings, поэтому вы не можете использовать Node bindings с linuxstatic.

API

const { exec } = require('pkg')

exec(args) принимает массив аргументов командной строки и возвращает промис. Например:

await exec(['app.js', '--target', 'host', '--output', 'app.exe']);
// что-то делаем с app.exe, запускаем, тестируем, загружаем, развертываем и т.д.

Устранение неполадок

Ошибка: ENOENT: no such file or directory, uv_chdir

Эта ошибка может быть вызвана удалением директории, из которой запускается приложение. Или, вообще, удалением директории process.cwd() при выполнении приложения.

Ошибка: ERR_INSPECTOR_NOT_AVAILABLE

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

Ошибка: require(...).internalModuleStat не является функцией

Эта ошибка может возникнуть при использовании переменной NODE_OPTIONS с некоторыми опциями загрузки или node, что может вызвать конфликты с pkg. Некоторые среды разработки, такие как VS Code, могут автоматически добавлять эту переменную окружения.Вы можете проверить это на Unix системах (Linux/macOS) в bash:

$ printenv | grep NODE

Расширенные возможности

Исследование виртуальной файловой системы, встроенной в режим отладки

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

$ pkg --debug app.js -o output
$ DEBUG_PKG=1 output

или

C:\> pkg --debug app.js -o output.exe
C:\> set DEBUG_PKG=1
C:\> output.exe

Примечание: убедитесь, что не используете флаг --debug в производственной среде.