deno compile

Флаги

Как и в случае с deno install, флаги среды выполнения, используемые для запуска скрипта, необходимо указать во время компиляции. Сюда входят флаги разрешений.

deno compile --allow-read --allow-net jsr:@std/http/file-server

Аргументы скрипта можно частично встроить.

deno compile --allow-read --allow-net jsr:@std/http/file-server -p 8080

./file_server --help

Обнаружение фреймворков

Начиная с Deno 2.8, deno compile . (или deno compile <directory>) обнаруживает распространённые веб-фреймворки и создаёт точку входа, которая умеет запускать их. Сначала выполняется обнаруженный скрипт сборки, поэтому скомпилированный бинарный файл всегда содержит актуальную сборку.

Поддерживаемые фреймворки:

• Next.js
• Astro
• Fresh (1.x и 2.x)
• Remix
• React Router
• SvelteKit
• Nuxt
• SolidStart
• TanStack Start
• Vite (SSR, а также SPA/MPA-проекты, отдаваемые как статические файлы)

# In a Next.js / Astro / Fresh / React Router / etc. project
deno compile .

# Or pointing at a specific app directory
deno compile ./apps/web

Сгенерированные точки входа используют import.meta.dirname, чтобы пути к ресурсам фреймворка правильно разрешались относительно виртуальной файловой системы внутри скомпилированного бинарного файла.

Перед компиляцией проекты React Router должны успешно собираться в Deno. Поскольку серверная точка входа React Router по умолчанию предназначена для Node.js, при сборке с Deno добавьте app/entry.server.tsx, совместимый с Web Streams. Пример см. в замечаниях о фреймворке React Router для настольных приложений.

Если проект не соответствует ни одному из поддерживаемых фреймворков, deno compile завершится с ошибкой.

Режим наблюдения

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

deno compile --watch main.ts

Используйте --watch-exclude, чтобы указать пути, изменения в которых не будут запускать пересборку, а --no-clear-screen — чтобы сохранять вывод терминала между пересборками:

deno compile --watch --watch-exclude=./dist --no-clear-screen main.ts

Кросс-компиляция

С помощью флага --target можно выполнять кросс-компиляцию бинарных файлов для других платформ.

# Cross compile for Apple Silicon
deno compile --target aarch64-apple-darwin main.ts

# Cross compile for Windows with an icon
deno compile --target x86_64-pc-windows-msvc --icon ./icon.ico main.ts

Поддерживаемые цели

Deno поддерживает кросс-компиляцию для всех целей независимо от платформы хоста.

aarch64-pc-windows-msvc (Windows на ARM) поддерживается начиная с Deno 2.9.3.

Бинарный файл denort

deno compile встраивает вашу программу в denort («среду выполнения Deno»): урезанную сборку Deno, содержащую только то, что необходимо для запуска скомпилированной программы, без подкоманд для работы с инструментами. Использование denort в качестве основы вместо полного бинарного файла deno позволяет уменьшить размер скомпилированных исполняемых файлов.

При первой компиляции для определённой версии Deno и целевой платформы Deno загружает соответствующий denort-<target>.zip из dl.deno.land и кэширует его в DENO_DIR. Так же работает и кросс-компиляция: при компиляции с --target загружается denort для этой платформы. При последующих компиляциях используется бинарный файл из кэша, поэтому они выполняются без подключения к сети.

Чтобы использовать в качестве основы пользовательскую или собранную локально среду выполнения, задайте переменную окружения DENORT_BIN, указав путь к ней. Deno также обнаруживает бинарный файл denort, размещённый рядом с исполняемым файлом deno.

Выбор движка JavaScript

По умолчанию скомпилированные бинарные файлы работают на V8. Флаг --engine позволяет вместо этого выполнить сборку с QuickJS, что даёт более компактный исполняемый файл:

# Default, same as omitting the flag
deno compile --engine v8 main.ts

# Build a binary that runs on QuickJS
deno compile --engine quickjs main.ts

Этот же флаг доступен для deno desktop и позволяет выбрать движок, встроенный в библиотеку среды выполнения приложения.

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

• Обновления безопасности. Бэкэнд QuickJS не получает таких же обновлений безопасности, как V8. Не используйте его для программ, выполняющих недоверенный код.
• Производительность. QuickJS — интерпретатор без JIT, поэтому вычислительно сложный код работает медленнее, чем на V8. При этом запуск происходит быстрее, а памяти используется меньше.
• Зрелость. Бэкэнд является экспериментальным; возможны отличия в поведении от V8, поэтому протестируйте программу на том движке, с которым собираетесь её выпускать.

Для каждого движка используется собственная предварительно собранная среда выполнения: с --engine quickjs Deno загружает denort-quickjs-<target>.zip (или libdenort-quickjs-<target>.zip для deno desktop) вместо стандартного denort-<target>.zip. Оба варианта публикуются для каждой поддерживаемой цели, поэтому кросс-компиляция выполняется одинаково. Если вы переопределите базовую среду выполнения с помощью DENORT_BIN (или бинарного файла denort рядом с deno), этот бинарный файл будет использоваться без изменений: в таком случае --engine игнорируется, а Deno выводит предупреждение.

Значки

При сборке для Windows к исполняемому файлу можно добавить значок с помощью флага --icon. Значок должен быть в формате .ico.

deno compile --icon icon.ico main.ts

# Cross compilation with icon
deno compile --target x86_64-pc-windows-msvc --icon ./icon.ico main.ts

Динамические импорты

По умолчанию статически анализируемые динамические импорты (импорты, в которых строковый литерал указан в выражении вызова import("...")) включаются в результат.

// calculator.ts and its dependencies will be included in the binary
const calculator = await import("./calculator.ts");

Однако динамические импорты, которые нельзя статически проанализировать, не включаются:

const specifier = condition ? "./calc.ts" : "./better_calc.ts";
const calculator = await import(specifier);

Чтобы включить динамические импорты, которые нельзя статически проанализировать, укажите флаг --include <path>.

deno compile --include calc.ts --include better_calc.ts main.ts

Включение файлов данных или каталогов

Начиная с Deno 2.1, файлы и каталоги можно включать в исполняемый файл, указав их с помощью флага --include <path>.

deno compile --include names.csv --include data main.ts

Затем прочитайте файл относительно пути к каталогу текущего модуля с помощью import.meta.dirname:

// main.ts
const names = Deno.readTextFileSync(import.meta.dirname + "/names.csv");
const dataFiles = Deno.readDirSync(import.meta.dirname + "/data");

// use names and dataFiles here

Обратите внимание: сейчас это работает только с файлами в файловой системе, но не с удалёнными файлами.

--include рассматривает встроенные файлы .js и .ts как корни графа модулей, поэтому разрешает их зависимости и транспилирует их. Чтобы встроить файлы в исходном виде, без разрешения модулей, используйте вместо этого --include-as-is. Это подходящий вариант для предварительно собранных фронтенд-пакетов (например, результатов сборки Vite или webpack), которые уже обработаны и не смогут разрешиться как модули Deno:

deno compile --include-as-is ./dist main.ts

Настройка include / exclude в deno.json

Пути --include и --exclude можно задать декларативно в deno.json, чтобы не указывать их повторно при каждом вызове deno compile:

{
  "compile": {
    "include": ["names.csv", "data", "worker.ts"],
    "exclude": ["data/secrets", "**/*.test.ts"]
  }
}

Флаги CLI объединяются с конфигурацией: --include и --exclude дополняют списки в deno.json, а не заменяют их. Подробнее, в том числе о том, как указать permissions в том же блоке, см. раздел Конфигурация компиляции в руководстве по конфигурации.

Воркеры

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

1. Используйте флаг --include <path>, чтобы включить код воркера.

deno compile --include worker.ts main.ts

2. Импортируйте модуль воркера с помощью статически анализируемого импорта.

// main.ts
import "./worker.ts";

deno compile main.ts

Объединение зависимостей

По умолчанию deno compile встраивает в исполняемый файл всё дерево разрешённых node_modules. Для проектов со множеством npm-зависимостей это может привести к увеличению размера бинарных файлов и замедлению запуска. Флаг --bundle вместо этого перед встраиванием передаёт точку входа в сборщик, поэтому в бинарный файл попадает только код, действительно используемый программой.

deno compile --bundle main.ts

Для дерева зависимостей, состоящего только из ESM, удаление неиспользуемого кода убирает всё лишнее, а полезная нагрузка npm исключается целиком, что позволяет значительно уменьшить размер бинарного файла. Если встречается пакет CommonJS или нативное дополнение (.node), необходимые пакеты встраиваются, чтобы продолжить работать во время выполнения, но неиспользуемые пакеты по-прежнему исключаются.

--bundle автоматически распознаёт несколько распространённых на практике шаблонов:

• CommonJS и нативные дополнения — зависимости CJS и нативные дополнения .node обнаруживаются, а содержащие их пакеты встраиваются.
• Воркеры — обнаруживаются вызовы new Worker(new URL("./worker.ts", import.meta.url), ...), каждый воркер собирается отдельно и встраивается вместе с основным пакетом.
• Чтение package.json — файлы package.json пакетов, которые читаются во время выполнения (например, для отображения версии), включаются автоматически.

Минификация пакета

Используйте --bundle вместе с --minify, чтобы минифицировать результат сборки. Это уменьшает размер встроенного пакета и расход памяти во время выполнения, но делает трассировки стека менее понятными.

deno compile --bundle --minify main.ts

--minify имеет смысл использовать только вместе с --bundle.

Ограничения

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

• Динамические require() / import() спецификаторов, которые не являются строковыми литералами.
• Воркеры, запускаемые с вычисляемыми URL или из транзитивных зависимостей, а не из собственного исходного кода.

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

Самораспаковывающиеся исполняемые файлы

По умолчанию скомпилированные исполняемые файлы предоставляют встроенные файлы через виртуальную файловую систему в памяти. Флаг --self-extracting меняет это поведение: при первом запуске бинарный файл извлекает все встроенные файлы на диск, а во время выполнения использует обычные операции с файловой системой.

deno compile --self-extracting main.ts

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

Каталог для извлечения выбирается в следующем порядке:

1. <exe_dir>/.<exe_name>/<hash>/ (рядом со скомпилированным бинарным файлом)
2. Резервный вариант — системный каталог данных платформы:
   • Linux: $XDG_DATA_HOME/<exe_name>/<hash> или ~/.local/share/<exe_name>/<hash>
   • macOS: ~/Library/Application Support/<exe_name>/<hash>
   • Windows: %LOCALAPPDATA%\<exe_name>\<hash>

Файлы извлекаются только один раз: при последующих запусках используется уже созданный каталог, если он существует и его хеш совпадает.

Компромиссы

Режим самораспаковки обеспечивает более широкую совместимость, но имеет некоторые недостатки:

• Первоначальный запуск: первый запуск занимает больше времени из-за извлечения файлов.
• Использование диска: извлечённые файлы занимают дополнительное место на диске.
• Использование памяти: расход памяти увеличивается, поскольку встроенное содержимое больше нельзя использовать как статические данные.
• Риск изменения: пользователи и другой код могут изменить извлечённые файлы на диске.

Подписание кода

macOS

По умолчанию в macOS скомпилированный исполняемый файл подписывается специальной подписью, что эквивалентно запуску codesign -s -:

deno compile -o main main.ts
codesign --verify -vv ./main

./main: valid on disk
./main: satisfies its Designated Requirement

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

codesign -s "Developer ID Application: Your Name" ./main

Подробнее о подписании кода и нотариальном заверении в macOS см. в официальной документации.

Windows

В Windows скомпилированный исполняемый файл можно подписать с помощью утилиты SignTool.exe.

deno compile -o main.exe main.ts
signtool sign /fd SHA256 main.exe

Постоянное хранилище в исполняемых файлах

Скомпилированный бинарный файл рассматривается как самостоятельное приложение, поэтому хранилище, привязанное к источнику, сохраняет данные между запусками в каталоге данных приложений платформы (%LOCALAPPDATA% в Windows, ~/Library/Application Support в macOS, $XDG_DATA_HOME в Linux):

• localStorage и API кэша Web читают данные из этого каталога и записывают их туда.
• Deno.openKv(), вызванный без указания пути, открывает в этом каталоге постоянную базу данных, а не использует базу данных в памяти.

Каждое скомпилированное приложение получает отдельное расположение, определяемое его идентификатором, поэтому приложения не используют общее хранилище. Идентификатор задаётся флагом --app-name, встраивается во время компиляции и, если он не указан, заменяется именем выходного файла:

deno compile --app-name my-app main.ts

Поскольку расположение определяется именем, а не путём к модулю, хранилище остаётся неизменным между запусками, даже если переименовать бинарный файл; два бинарных файла, собранные с одинаковым --app-name, используют общее хранилище, а приложения с разными именами изолированы друг от друга. Повторная компиляция с другим --app-name создаёт новое хранилище.