Проверка версии и базовые флаги помощи

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

CLI-проверка версии

Наиболее прямой способ получения версии — обращение к бинарному файлу:

esbuild --version

или сокращённая форма:

esbuild -v

Вывод содержит строку вида:

0.20.2

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

npx esbuild --version

или

pnpm esbuild --version
yarn esbuild --version

Использование npx гарантирует запуск локально установленной версии, игнорируя глобальные установки.

Проверка версии через npm-пакет

При работе в Node.js окружении версия доступна напрямую из метаданных пакета:

const esbuild = require("esbuild");

console.log(esbuild.version);

Вывод — строка версии, совпадающая с CLI:

0.20.2

Альтернативный способ — чтение package.json:

const { version } = require("esbuild/package.json");

console.log(version);

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

Проверка установленной версии через npm

Контроль установленного пакета в проекте:

npm list esbuild

или более компактно:

npm ls esbuild --depth=0

Пример вывода:

esbuild@0.20.2

Для Yarn:

yarn list --pattern esbuild

Для pnpm:

pnpm list esbuild

Глобальная и локальная установка

При наличии нескольких установок возможны расхождения:

  • глобальная версия (установлена через npm i -g esbuild)
  • локальная версия (в node_modules проекта)

Проверка глобальной версии:

npm list -g esbuild

или:

esbuild --version

(если PATH указывает на глобальную установку)

Локальная версия предпочтительнее в CI и production-сборках, так как обеспечивает воспроизводимость.

Использование в CI и контроль воспроизводимости

В системах непрерывной интеграции фиксирование версии является обязательной практикой. Версия esbuild должна совпадать с lockfile:

  • package-lock.json
  • yarn.lock
  • pnpm-lock.yaml

Проверка в CI часто выполняется через:

npx esbuild --version

или через node-скрипт:

const esbuild = require("esbuild");

if (!esbuild.version.startsWith("0.20")) {
  throw new Error("Unexpected esbuild version");
}

Такой контроль предотвращает регрессии при автоматических обновлениях зависимостей.

Базовые флаги помощи

Общая справка

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

esbuild --help

или:

esbuild -h

Вывод содержит список основных команд и глобальных параметров, включая:

  • build
  • transform
  • serve
  • входные и выходные опции
  • параметры минификации
  • настройки sourcemap

Справка по подкомандам

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

esbuild --help=build
esbuild --help=transform
esbuild --help=serve

Каждый режим выводит только релевантные флаги, уменьшая шум и упрощая навигацию по API.

Структура help-вывода

Справочная информация организована по блокам:

  • Usage — формат запуска команды
  • Options — список параметров
  • Advanced options — низкоуровневые настройки
  • Platform-specific flags — различия между Node, browser и CLI
  • Examples — типовые сценарии использования

Особенность esbuild заключается в плотной связке CLI и API: большинство флагов напрямую соответствуют параметрам JavaScript API.

Часто используемые флаги в контексте help

Некоторые ключевые параметры, отображаемые в справке:

  • --bundle — включение бандлинга
  • --minify — минификация кода
  • --sourcemap — генерация source maps
  • --outfile — выходной файл
  • --outdir — выходная директория
  • --format — формат модулей (esm, cjs, iife)
  • --platform — target окружение (node, browser, neutral)
  • --target — версия ECMAScript

Эти параметры часто комбинируются, формируя базовые профили сборки.

Диагностика через help-флаги

Help-режим используется не только для изучения API, но и для диагностики:

  • проверка доступности бинарника в PATH
  • подтверждение корректной установки
  • проверка версии косвенно через наличие новых опций
  • выявление конфликтов между глобальной и локальной версиями

Поведение при ошибках запуска

При отсутствии бинарника или некорректной установке:

esbuild --version

может возвращать:

  • command not found
  • или ошибку разрешения модуля в Node

В таких случаях справка недоступна, что указывает на проблему уровня установки, а не конфигурации.

Взаимосвязь версии и help-вывода

Разные версии esbuild могут:

  • добавлять новые флаги
  • деактивировать устаревшие параметры
  • менять поведение существующих опций
  • расширять help-секции

Поэтому help-вывод всегда следует рассматривать как версионно-зависимый источник информации, а не как статическую документацию.

Оглавление