Константы времени сборки с --define в bun build

Флаг --define можно использовать с bun build и bun build --compile для внедрения констант времени сборки в ваше приложение. Это особенно полезно для встраивания метаданных, таких как версии сборки, временные метки или флаги конфигурации, непосредственно в скомпилированные исполняемые файлы.

bun build --compile --define BUILD_VERSION='"1.2.3"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/index.ts --outfile myapp

Зачем использовать константы времени сборки?

Константы времени сборки встраиваются непосредственно в скомпилированный код, что делает их:

Без накладных расходов во время выполнения - Нет поисков переменных окружения или чтений файлов
Неизменяемыми - Значения встроены в двоичный файл во время компиляции
Оптимизируемыми - Удаление мёртвого кода может удалить неиспользуемые ветви
Безопасными - Нет внешних зависимостей или файлов конфигурации для управления

Это похоже на gcc -D или #define в C/C++, но для JavaScript/TypeScript.

Основное использование

С `bun build`

# Сборка с константами времени сборки
bun build --define BUILD_VERSION='"1.0.0"' --define NODE_ENV='"production"' src/index.ts --outdir ./dist

С `bun build --compile`

# Компиляция в исполняемый файл с константами времени сборки
bun build --compile --define BUILD_VERSION='"1.0.0"' --define BUILD_TIME='"2024-01-15T10:30:00Z"' src/cli.ts --outfile mycli

JavaScript API

await Bun.build({
  entrypoints: ["./src/index.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: '"1.0.0"',
    BUILD_TIME: '"2024-01-15T10:30:00Z"',
    DEBUG: "false",
  },
});

Распространённые варианты использования

Информация о версии

Встройте версию и метаданные сборки непосредственно в исполняемый файл:

// Эти константы заменяются во время сборки
declare const BUILD_VERSION: string;
declare const BUILD_TIME: string;
declare const GIT_COMMIT: string;

export function getVersion() {
  return {
    version: BUILD_VERSION,
    buildTime: BUILD_TIME,
    commit: GIT_COMMIT,
  };
}

bun build --compile \
  --define BUILD_VERSION='"1.2.3"' \
  --define BUILD_TIME='"2024-01-15T10:30:00Z"' \
  --define GIT_COMMIT='"abc123"' \
  src/cli.ts --outfile mycli

Флаги функций

Используйте константы времени сборки для включения/отключения функций:

// Заменяется во время сборки
declare const ENABLE_ANALYTICS: boolean;
declare const ENABLE_DEBUG: boolean;

function trackEvent(event: string) {
  if (ENABLE_ANALYTICS) {
    // Этот блок полностью удаляется, если ENABLE_ANALYTICS равен false
    console.log("Отслеживание:", event);
  }
}

if (ENABLE_DEBUG) {
  console.log("Режим отладки включён");
}

# Продакшен сборка - аналитика включена, отладка отключена
bun build --compile --define ENABLE_ANALYTICS=true --define ENABLE_DEBUG=false src/app.ts --outfile app-prod

# Сборка для разработки - оба включены
bun build --compile --define ENABLE_ANALYTICS=false --define ENABLE_DEBUG=true src/app.ts --outfile app-dev

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

Заменяйте объекты конфигурации во время сборки:

declare const CONFIG: {
  apiUrl: string;
  timeout: number;
  retries: number;
};

// CONFIG заменяется фактическим объектом во время сборки
const response = await fetch(CONFIG.apiUrl, {
  timeout: CONFIG.timeout,
});

bun build --compile --define 'CONFIG={"apiUrl":"https://api.example.com","timeout":5000,"retries":3}' src/app.ts --outfile app

Расширенные паттерны

Сборки для разных окружений

Создавайте разные исполняемые файлы для разных окружений:

json

{
  "scripts": {
    "build:dev": "bun build --compile --define NODE_ENV='\"development\"' --define API_URL='\"http://localhost:3000\"' src/app.ts --outfile app-dev",
    "build:staging": "bun build --compile --define NODE_ENV='\"staging\"' --define API_URL='\"https://staging.example.com\"' src/app.ts --outfile app-staging",
    "build:prod": "bun build --compile --define NODE_ENV='\"production\"' --define API_URL='\"https://api.example.com\"' src/app.ts --outfile app-prod"
  }
}

Использование команд оболочки для динамических значений

Генерируйте константы времени сборки из команд оболочки:

# Используйте git для получения текущего коммита и временной метки
bun build --compile \
  --define BUILD_VERSION="\"$(git describe --tags --always)\"" \
  --define BUILD_TIME="\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"" \
  --define GIT_COMMIT="\"$(git rev-parse HEAD)\"" \
  src/cli.ts --outfile mycli

Скрипт автоматизации сборки

Создайте скрипт сборки, который автоматически внедряет метаданные сборки:

// build.ts
import { $ } from "bun";

const version = await $`git describe --tags --always`.text();
const buildTime = new Date().toISOString();
const gitCommit = await $`git rev-parse HEAD`.text();

await Bun.build({
  entrypoints: ["./src/cli.ts"],
  outdir: "./dist",
  define: {
    BUILD_VERSION: JSON.stringify(version.trim()),
    BUILD_TIME: JSON.stringify(buildTime),
    GIT_COMMIT: JSON.stringify(gitCommit.trim()),
  },
});

console.log(`Сборка с версией ${version.trim()}`);

Важные замечания

Формат значения

Значения должны быть допустимым JSON, который будет разобран и встроен как выражения JavaScript:

# ✅ Строки должны быть в кавычках JSON
--define VERSION='"1.0.0"'

# ✅ Числа являются литералами JSON
--define PORT=3000

# ✅ Булевы значения являются литералами JSON
--define DEBUG=true

# ✅ Объекты и массивы (используйте одинарные кавычки для обёртывания JSON)
--define 'CONFIG={"host":"localhost","port":3000}'

# ✅ Массивы тоже работают
--define 'FEATURES=["auth","billing","analytics"]'

# ❌ Это не сработает - отсутствуют кавычки вокруг строки
--define VERSION=1.0.0

Ключи свойств

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

# ✅ Заменить process.env.NODE_ENV на "production"
--define 'process.env.NODE_ENV="production"'

# ✅ Заменить process.env.API_KEY на фактический ключ
--define 'process.env.API_KEY="abc123"'

# ✅ Заменить вложенные свойства
--define 'window.myApp.version="1.0.0"'

# ✅ Заменить доступ к массиву
--define 'process.argv[2]="--production"'

Это особенно полезно для переменных окружения:

// Перед компиляцией
if (process.env.NODE_ENV === "production") {
  console.log("Режим продакшена");
}

// После компиляции с --define 'process.env.NODE_ENV="production"'
if ("production" === "production") {
  console.log("Режим продакшена");
}

// После оптимизации
console.log("Режим продакшена");

Объявления TypeScript

Для проектов TypeScript объявите константы, чтобы избежать ошибок типов:

// types/build-constants.d.ts
declare const BUILD_VERSION: string;
declare const BUILD_TIME: string;
declare const NODE_ENV: "development" | "staging" | "production";
declare const DEBUG: boolean;

Кроссплатформенная совместимость

При сборке для нескольких платформ константы работают одинаково:

# Linux
bun build --compile --target=bun-linux-x64 --define PLATFORM='"linux"' src/app.ts --outfile app-linux

# macOS
bun build --compile --target=bun-darwin-x64 --define PLATFORM='"darwin"' src/app.ts --outfile app-macos

# Windows
bun build --compile --target=bun-windows-x64 --define PLATFORM='"windows"' src/app.ts --outfile app-windows.exe

См. также

Определение констант во время выполнения - Использование --define с bun run
Сборка исполняемых файлов - Полное руководство по bun build --compile
API сборщика - Полная документация сборщика, включая опцию define

Зачем использовать константы времени сборки? ​

Основное использование ​

С bun build ​

С bun build --compile ​

JavaScript API ​

Распространённые варианты использования ​

Информация о версии ​

Флаги функций ​

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

Расширенные паттерны ​

Сборки для разных окружений ​

Использование команд оболочки для динамических значений ​

Скрипт автоматизации сборки ​

Важные замечания ​

Формат значения ​

Ключи свойств ​

Объявления TypeScript ​

Кроссплатформенная совместимость ​

См. также ​