Squoosh CLI: возможности, форматы, ограничения и текущий статус поддержки

Squoosh CLI — это опубликованный в npm пакет @squoosh/cli, который переносит кодеки проекта Squoosh в командную строку через Node.js и WebAssembly. Он рассчитан прежде всего на пакетную подготовку изображений для сайтов и автоматизированных сборок: один запуск может принять несколько файлов, выполнить предварительную обработку и записать версии в JPEG, PNG, WebP, AVIF, JPEG XL или WebP2. При этом актуальное состояние продукта принципиально важно для оценки: последняя опубликованная версия 0.7.3 вышла 3 января 2023 года, а сам пакет больше не поддерживается разработчиками. Поэтому сегодня Squoosh CLI разумно рассматривать как замороженный экспериментальный инструмент и часть истории Squoosh, а не как современный активно развиваемый CLI для новых проектов.

Задать вопрос фотографу

Андрей Фёдоров

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

Задать вопрос

Что такое Squoosh CLI и чем он отличается от Squoosh

Проект Squoosh появился как браузерное приложение команды Google Chrome Developers для сравнения и сжатия изображений. В конце 2020 года вместе с Squoosh v2 команда представила отдельный вариант для командной строки. Его задача была другой: не показывать интерактивное сравнение двух вариантов изображения, а дать автоматизации доступ к тем же WebAssembly-кодекам из Node.js. Позднее общую программную часть вынесли в экспериментальную библиотеку @squoosh/lib, поверх которой построен CLI.

В этом обзоре рассматривается именно официальный пакет @squoosh/cli версии 0.7.3, автором которого в метаданных указан Google Chrome Developers. Его не следует смешивать с веб-приложением Squoosh, сторонними мобильными приложениями с похожим названием и более поздними независимыми форками npm-пакета. Веб-версия имеет графический интерфейс и продолжила развиваться отдельно, тогда как CLI и libSquoosh были оставлены без активной поддержки.

Такое разделение влияет на практический выбор. Читателю, которому нужно визуально сравнить качество до и после сжатия, удобнее актуальный Squoosh в браузере. Squoosh CLI предназначался для другой модели работы: заранее задать параметры в команде, передать один файл, список файлов или каталог, дождаться обработки и получить готовые файлы на диске. Это автоматизирует повторяющиеся операции, но лишает пользователя встроенного визуального контроля.

Основные параметры

Текущий статус и требования к среде

Почему статус поддержки важнее списка функций

README версии 0.7.3 прямо помечает проект как больше не поддерживаемый. Там же Squoosh CLI назван экспериментальным способом запуска кодеков Squoosh. Это не формальная пометка о «старой версии»: разработчики отдельно объяснили, что времени и команды для сопровождения CLI и libSquoosh больше нет, при этом браузерный Squoosh продолжил поддерживаться. Следовательно, ошибки совместимости с новыми версиями Node.js, проблемы WebAssembly и старые ограничения CLI нельзя оценивать так же, как в живом проекте, где можно рассчитывать на последующий патч.

Пакет всё ещё доступен в npm, поэтому его можно найти и установить. Доступность дистрибутива, однако, не означает актуальную поддержку. Для нового производственного процесса важны не только возможности кодеков, но и жизненный цикл зависимостей. В Squoosh CLI эти два аспекта расходятся: набор операций остаётся интересным, а среда, для которой опубликован пакет, зафиксирована на старых ветках Node.js.

Node.js и отсутствие отдельных сборок для ОС

Squoosh CLI не поставляется как отдельный установщик для Windows, macOS или Linux. Это пакет JavaScript с точкой входа командной строки, который запускается Node.js. В package.json версии 0.7.3 поле engines ограничивает совместимую среду ветками ^12.20.2, ^14.13.1 или ^16.0.0. Node.js 18 и более новые ветки в этот диапазон не входят. В трекере проекта зафиксированы сбои при запуске на Node.js 18, связанные с загрузкой локальных WebAssembly-модулей.

Из этого следует практическое ограничение: проверять Squoosh CLI на современной системе нужно не по названию операционной системы, а по фактической версии Node.js и поведению зависимостей. На компьютере может быть полностью актуальная ОС, но установленный Node окажется слишком новым для заявленного диапазона пакета. Для воспроизведения старого процесса разумнее изолированная среда с подходящей версией Node, чем замена основной рабочей среды на устаревшую ветку.

Отдельной мобильной редакции Squoosh CLI нет. Это терминальная утилита для среды, где можно запускать Node.js и работать с файловой системой. Она не заменяет приложение для Android или iOS и не предлагает сенсорного интерфейса, камеры, системной галереи или мобильного экспорта.

Установка и запуск

Документация предусматривает два режима. Первый — запуск через npx без постоянной глобальной установки пакета. Второй — глобальная установка через npm, после которой используется команда squoosh-cli. В обоих случаях набор функций одинаков, потому что речь идёт об одном npm-пакете. Для первого запуска npx сеть обычно нужна, чтобы получить пакет и его зависимости из реестра, если они ещё не находятся в локальном кэше.

После получения пакета сам процесс обработки не устроен как облачный сервис. Опубликованный исходный файл CLI читает входные файлы через модуль файловой системы Node.js, передаёт их в ImagePool, запускает локальные WebAssembly-кодеки и записывает бинарный результат обратно на диск. В коде CLI нет этапа загрузки пользовательского изображения на удалённый сервер. Это важное отличие от сервисов, где компрессия выполняется после отправки файла в облако.

Как устроен интерфейс Squoosh CLI

Графического окна у утилиты нет, поэтому привычные понятия «панель инструментов», «холст» и «окно экспорта» здесь неприменимы. Рабочий интерфейс состоит из команды запуска, аргументов, индикатора состояния и текстового отчёта. С точки зрения пользователя это четыре функциональные зоны, которые появляются последовательно в терминале.

Командная строка и аргументы

Базовая форма вызова — squoosh-cli [options] <files…>. После параметров передаются пути к изображениям или каталогам. Опция -d или –output-dir определяет каталог результата и по умолчанию равна текущей директории. Опция -s или –suffix добавляет суффикс к имени выходного файла и по умолчанию оставлена пустой.

Параметры преобразований представлены отдельными ключами. –resize включает изменение размера, –quant — сокращение числа цветов, –rotate — поворот. Настройки передаются строкой, которую программа разбирает через JSON5. Такое устройство даёт больше свободы, чем набор нескольких жёстко заданных пресетов, но одновременно делает команду чувствительной к кавычкам и экранированию в конкретной оболочке.

Выбор кодека

Каждый выходной кодек включается своим ключом: –mozjpeg, –webp, –avif, –jxl, –wp2 и –oxipng. Можно указать больше одного кодека в одном запуске. Исходный код формирует объект настроек для каждого выбранного энкодера, выполняет кодирование, а затем проходит по всем полученным версиям и записывает их с соответствующими расширениями.

Это один из наиболее полезных аспектов архитектуры Squoosh CLI для веб-пайплайна: один исходник можно превратить, например, одновременно в WebP и AVIF, не создавая два независимых прохода вручную. Однако текущие параметры кодеков привязаны к замороженной версии @squoosh/lib, поэтому совпадение с современной веб-версией Squoosh по набору опций и результатам не гарантируется.

Индикаторы Decoding и Encoding

После запуска утилита выводит этап Decoding… и прогресс по количеству входных файлов. Затем появляется состояние Encoding с количеством потоков workers. Число работников в CLI создаётся по количеству CPU-ядер, которое возвращает Node.js. Отдельного флага для ограничения числа workers в версии 0.7.3 нет.

Такой подход хорошо соответствует пакетной задаче: несколько изображений могут находиться в обработке параллельно. Но он означает и отсутствие простого встроенного регулятора нагрузки. На машине с большим числом логических ядер CLI стремится задействовать большой пул, а администратор не может снизить его размер обычным аргументом команды. Для контролируемой серверной нагрузки это заметное ограничение по сравнению с инструментами, где количество потоков задаётся явно.

Финальный отчёт Squoosh results

После завершения программа выводит блок Squoosh results:. Для каждого исходника указывается его размер, а ниже — путь к каждому записанному результату, новый размер и отношение размера результата к оригиналу в процентах. Если результат больше исходника, код терминального вывода выделяет процент другим цветом. Это полезная проверка, потому что сама по себе перекодировка не гарантирует уменьшения файла.

Отчёт не является визуальным сравнением качества. В нём нет увеличенного фрагмента, режима до/после, карты артефактов или интерактивного ползунка. Поэтому финальный процент отвечает только на вопрос о размере, а приемлемость артефактов нужно проверять отдельно просмотром полученных изображений.

Основные функции и их связь в конвейере

Импорт одного файла, списка файлов и каталога

В аргументах можно передать несколько путей. Если путь указывает на обычный файл, он добавляется в очередь. Если путь указывает на каталог, Squoosh CLI читает его содержимое и берёт только элементы верхнего уровня, которые файловая система определяет как файлы. Подкаталоги не обходятся рекурсивно. Это подтверждается реализацией getInputFiles: для директории используется readdir с withFileTypes, затем остаются только элементы с isFile.

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

Есть ещё одно следствие: структура исходных каталогов не переносится в папку результата. Выходное имя строится из basename исходного файла, выбранного суффикса и расширения кодека. Если в одной операции участвуют два изображения с одинаковым базовым именем из разных каталогов и оба пишутся в один output-dir, их результаты могут получить одинаковые пути. Это создаёт риск перезаписи и требует заранее исключать коллизии имён.

Изменение размера

Resize выполняется до кодирования. Библиотека, на которой построен CLI, поддерживает задание ширины и высоты; при указании обоих значений изображение приводится к заданному размеру. Если задано только одно измерение, второе рассчитывается с сохранением пропорций. Для веб-публикации это позволяет объединить уменьшение разрешения и смену формата в одном конвейере.

Важна последовательность: исходник сначала декодируется, затем проходит выбранные preprocessors, после чего кодируется во все выбранные форматы. Поэтому WebP и AVIF, созданные за один запуск после resize, получают уже обработанную версию с одинаковыми итоговыми геометрическими параметрами. Не нужно отдельно уменьшать JPEG перед каждым энкодером.

Quant: сокращение палитры

Ключ –quant подключает предварительное уменьшение количества используемых цветов. В составе @squoosh/lib 0.4.0 для этой операции присутствует WebAssembly-модуль imagequant. Палетизация особенно связана с изображениями, где допустимо сократить число цветов до кодирования, однако качество результата зависит от конкретного исходника и настроек.

CLI не показывает интерактивный превью-результат quant. Поэтому применять сокращение палитры вслепую ко всему фотокаталогу неразумно: следует сначала проверить репрезентативные изображения и только затем переносить настройки на пакет. Сам факт уменьшения палитры не означает автоматического улучшения фотографии.

Поворот

Параметр –rotate добавляет поворот как ещё один preprocessor. Он выполняется до энкодеров, поэтому все форматы текущего запуска получают одинаково повернутое изображение. Отдельного графического контроллера ориентации нет: значение задаётся в конфигурации параметра.

Squoosh CLI не является полноценным редактором. В опубликованном наборе preprocessors, который CLI автоматически превращает в флаги, фигурируют resize, quant и rotate. Инструменты кадрирования, слои, кисти, ретушь, текст, маски и цветокоррекция не относятся к его интерфейсу. Если перед сжатием требуется содержательное редактирование кадра, его нужно выполнять другим приложением или другим этапом пайплайна.

MozJPEG и OxiPNG

MozJPEG используется для создания файлов с расширением JPG, а OxiPNG — PNG. Это важное отличие от простого «сменить расширение»: в обоих случаях задействован конкретный кодек из набора Squoosh. Параметры можно передавать объектом конфигурации, а неуказанные значения берутся из defaults соответствующей версии библиотеки.

Для PNG особенно важно помнить о выходном имени. По умолчанию output-dir равен текущему каталогу, а suffix пуст. Если исходник уже называется, например, photo.png и выбран OxiPNG, рассчитанный путь результата также может оказаться photo.png. Исходный код записывает результат через writeFile без автоматического резервного копирования. Поэтому безопасный рабочий процесс должен использовать отдельный каталог или непустой суффикс.

WebP, AVIF, JPEG XL и WebP2

CLI предоставляет отдельные энкодеры WebP, AVIF, JPEG XL и WebP2. Их можно комбинировать в одном запуске и получить несколько файлов разных форматов из одного декодированного исходника. Для подготовки веб-ассетов это и было одной из основных идей Squoosh CLI: разработчик мог создать несколько вариантов изображения и затем использовать нужные версии на стороне сайта.

Наличие энкодера в Squoosh CLI не означает, что конкретный формат автоматически подходит для текущей целевой платформы. Пакет 0.7.3 зафиксирован на кодеках своего времени. Совместимость готового файла с браузером, CMS, графическим редактором, CDN или приложением нужно проверять в той системе, куда результат действительно будет загружен. Это особенно важно для форматов, которые не входят в повседневный обмен изображениями во всех программах.

Экспериментальный auto и Butteraugli

Для кодека вместо объекта конфигурации можно передать значение auto. Тогда включается экспериментальный автооптимизатор, который стремится сжать изображение до целевой дистанции Butteraugli. В CLI предусмотрены два глобальных параметра этого процесса: максимальное число раундов оптимизации, по умолчанию 6, и целевая Butteraugli distance, по умолчанию 1.4.

Логика здесь отличается от фиксированного quality. Автооптимизатор несколько раз кодирует изображение, подбирая параметры к целевому уровню визуального различия. Более высокое целевое значение Butteraugli допускает больше артефактов. Из-за дополнительных раундов такой режим способен выполнять больше работы, чем одно кодирование с заранее заданным параметром качества.

Auto не превращает CLI в интеллектуальный фоторедактор. В пакете нет генеративных функций, распознавания объектов, дорисовки или нейросетевой ретуши. Автоматизация относится к подбору параметров компрессии по метрике визуального различия.

Поддерживаемые форматы и экспорт

Для форматов нужно разделять декодирование входа и гарантированно доступные выходные энкодеры. В опубликованной @squoosh/lib 0.4.0 присутствуют Node/WebAssembly-декодеры для AVIF, JPEG XL, JPEG через MozJPEG, WebP и WebP2, а также модуль PNG. Поэтому именно этот набор относится к формату данных, с которым работала библиотека той версии. GIF и SVG не входят в этот декодерный набор; запросы на их поддержку отдельно фиксировались в трекере проекта и не были реализованы как поддерживаемая возможность CLI.

RAW-файлы камер, TIFF, HEIC и документы PDF не заявлены как входы этого опубликованного набора декодеров Squoosh CLI. Для таких источников сначала нужен инструмент, который действительно умеет их декодировать, либо другой конвертер. Принудительная передача файла с неподдерживаемым содержимым не добавляет кодек автоматически.

Экспорт всегда файловый. CLI создаёт каталог результата рекурсивно при необходимости, формирует имя из базового имени исходника и suffix, затем добавляет расширение каждого энкодера. Нет диалога «Сохранить как», профилей экспорта с именами, облачного альбома или встроенной публикации в CMS.

Типичный рабочий сценарий

Хотя Squoosh CLI — не пошаговый редактор, его проще оценить на конкретном сценарии. Предположим, есть JPEG-фотография для карточки материала. Нужны две веб-версии шириной 1600 пикселей: WebP с явно заданным quality и AVIF в автоматическом режиме. Исходный JPEG необходимо сохранить нетронутым.

1. Работа выполняется в изолированной среде с Node.js, который входит в заявленный диапазон пакета 0.7.3.
2. Для результата заранее используется отдельная папка output, чтобы исключить перезапись исходника.
3. В команду добавляется resize только по ширине, чтобы библиотека сохранила пропорции.
4. Одновременно включаются два энкодера: WebP с заданной конфигурацией и AVIF со значением auto.
5. После Decoding и Encoding проверяется блок Squoosh results, затем оба файла визуально сравниваются с оригиналом в программе, которая умеет их корректно отображать.

Пример команды: npx @squoosh/cli –resize ‘{“width”:1600}’ –webp ‘{“quality”:75}’ –avif auto -d output photo.jpg

В среде, где оболочка по-другому трактует одиночные и двойные кавычки, синтаксис кавычек придётся адаптировать. Это не изменение настроек Squoosh, а особенность передачи строкового аргумента процессу. Внутри CLI содержимое параметров разбирается JSON5.

Результатом такого запуска должны стать версии с базовым именем photo и расширениями, соответствующими выбранным энкодерам, в указанном каталоге. Resize выполняется до обоих энкодеров, поэтому ширина выходов основана на одном предварительно обработанном изображении. AVIF в этом примере потребует дополнительные раунды подбора параметров, если это необходимо для auto.

Этот сценарий показывает сильную сторону CLI — получение нескольких производных файлов за один запуск — и одновременно его слабость. Командная строка не отвечает, приемлемо ли выглядит изображение при quality 75 или выбранной Butteraugli target. Визуальный контроль остаётся отдельным обязательным этапом.

Пакетная обработка и автоматизация

Несколько файлов за один запуск

Позиционный аргумент допускает несколько файлов. После получения списка Squoosh CLI сначала декодирует входы, затем применяет выбранные preprocessors и создаёт задачи кодирования. Для каждой картинки может быть сгенерировано несколько форматов. Это делает утилиту пригодной для однотипной обработки коллекции ассетов, где параметры известны заранее.

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

Параллелизм и использование процессора

ImagePool создаётся с количеством workers, равным числу CPU-ядер, доступных процессу. С точки зрения производительности это естественный выбор для пакетного кодирования: вместо последовательного ожидания каждого изображения библиотека распределяет работу по worker pool. Именно параллельную обработку разработчики называли одной из целей CLI и libSquoosh.

Для общей рабочей станции есть обратная сторона: в интерфейсе 0.7.3 отсутствует аргумент вроде workers или threads, позволяющий ограничить размер пула. Если компрессия запускается параллельно с рендерингом, сборкой или другой тяжёлой задачей, CLI нельзя штатно попросить использовать только часть ядер. Для такого сценария лучше средство с явным контролем concurrency либо собственный скрипт вокруг библиотеки, хотя сама @squoosh/lib также заморожена.

Память и большие пакеты

Реализация CLI читает каждый входной файл целиком через readFile, передаёт буфер в ImagePool и ожидает декодирование всех элементов через Promise.all до следующей стадии. Следовательно, большой пакет не обрабатывается как простая последовательность «прочитал один — записал один — освободил». Одновременно в конвейере может находиться много декодированных изображений и задач.

Документация не устанавливает универсальный предел размера файла или число изображений на один запуск. Поэтому безопасная оценка больших наборов должна опираться на фактическую память машины и размеры декодированных bitmap, а не только на размер JPEG или WebP на диске. Сжатый файл в несколько мегабайт после декодирования занимает память как массив пикселей, что особенно заметно на фотографиях большого разрешения.

Что автоматизируется, а что нет

• автоматизируются единые resize, quant и rotate для всей текущей команды;
• автоматизируется кодирование одного исходника сразу несколькими энкодерами;
• автоматизируется подбор компрессии через режим auto;
• обработка нескольких изображений распараллеливается worker pool;
• не предусмотрен рекурсивный обход дерева каталогов внутри самого CLI;
• нет встроенного watch-режима, который постоянно следит за папкой;
• нет графического пакетного профиля и интерактивного предпросмотра;
• нет облачной очереди или серверного кабинета с историей заданий.

Приватность, интернет и локальная обработка

В вопросе приватности Squoosh CLI выгодно отличается от облачных компрессоров: опубликованный код версии 0.7.3 работает с локальными путями, читает данные через файловую систему и кодирует их через локальный ImagePool. В процессе обработки изображения не предусмотрена отправка файла на сервер Squoosh. Выход также записывается в локальную файловую систему.

Это не означает, что сеть никогда не используется в жизненном цикле программы. npx при отсутствии пакета локально обращается к npm за пакетом и зависимостями, а npm install также требует получения дистрибутива. После установки обработка файла и сетевой доступ — разные этапы. Для изолированной среды зависимости можно подготовить заранее, но пакетный менеджер и его кэширование уже относятся к инфраструктуре Node.js, а не к функциям Squoosh CLI.

Регистрация пользователя для компрессии не предусмотрена. CLI не просит аккаунт Squoosh, API-ключ, адрес электронной почты или подписку. Вместе с тем локальная обработка не снимает ответственность за права доступа к файловой системе: процесс Node.js получает те же возможности чтения и записи, которые разрешены запустившему его пользователю.

Стоимость, лицензирование и редакции

@squoosh/cli 0.7.3 опубликован как публичный пакет с лицензией Apache-2.0. У него нет коммерческих редакций Basic, Pro или Enterprise, нет платного тарифа за количество изображений и нет пробного периода с ограничением экспорта. Компрессия не разблокируется оплатой.

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

Отдельной «настольной редакции Squoosh CLI» тоже нет. Веб-приложение Squoosh — другой интерфейс того же исторического семейства, а @squoosh/lib — программная библиотека для JavaScript. Они не являются платными уровнями одного продукта и не должны описываться как тарифные планы CLI.

Главные ограничения и риски

Замороженный диапазон Node.js

Самое серьёзное ограничение в 2026 году — не формат JPEG или отсутствие GUI, а заявленный runtime. Пакет 0.7.3 ожидает Node 12.20.2, 14.13.1 или 16.x. Попытка просто выполнить npx в современном проекте с более новой веткой Node находится за пределами объявленной совместимости. В истории проекта есть конкретные ошибки на Node 18, включая невозможность корректно разрешить путь к WebAssembly-файлам.

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

Риск перезаписи оригинала

Имя результата строится без исходного расширения, затем к нему добавляются suffix и расширение выбранного энкодера. При значениях по умолчанию output-dir равен точке, а suffix пуст. Поэтому OxiPNG для уже существующего PNG или MozJPEG для JPEG способен получить тот же путь, что и входной файл. writeFile записывает результат по вычисленному пути без автоматического резервного копирования.

Защита проста организационно: использовать отдельный output-dir либо суффикс, а оригиналы хранить отдельно. Это не рекомендация «на всякий случай», а прямое следствие алгоритма формирования имени. Важные исходники не следует отдавать процессу, который потенциально пишет по тому же пути.

Коллизии одинаковых basename

Похожая проблема возникает при объединении файлов из разных каталогов. В результирующий путь не переносится дерево папок — используется только basename. Два файла вида folder-a/photo.jpg и folder-b/photo.jpg, направленные в один output-dir и один формат без различающего suffix, претендуют на одинаковое имя результата. Поэтому перед крупной пакетной конвертацией нужно исключить повторяющиеся базовые имена или разбить работу по каталогам.

Нет рекурсивного обхода каталогов

Каталог обрабатывается только на один уровень. Это легко пропустить, если ожидать поведение инструмента для медиатеки. Наличие подкаталогов не вызывает автоматический обход — они просто не проходят фильтр isFile. Если после запуска количество результатов меньше ожидаемого, первым делом стоит сравнить структуру папки и число файлов именно на верхнем уровне.

Нет визуального контроля

Размер в процентах показывает экономию или увеличение объёма, но не качество. Автооптимизатор ориентируется на Butteraugli, а фиксированные настройки кодеков используют числовые параметры. Ни один из этих механизмов не заменяет просмотр сложных участков: мелкого текста, волос, контрастных границ, прозрачности, градиентов и текстур. Для окончательного выбора настроек нужен внешний просмотрщик или браузер.

Скорость не является целью проекта

README прямо предупреждает, что Squoosh CLI не задуман как самый быстрый компрессор изображений. Worker pool ускоряет пакетную работу, однако сами кодеки работают через WebAssembly, а auto способен выполнить несколько раундов. Если основной критерий — максимальная скорость серверной обработки, нужно сравнивать с нативными специализированными энкодерами на собственных типовых данных.

Плюсы и минусы

Кому подойдёт

Для воспроизведения существующего старого пайплайна. Если проект уже фиксирован на @squoosh/cli 0.7.3 и совместимой версии Node.js, обзор кода и параметров позволяет сохранить предсказуемый процесс. В таком сценарии особенно важно зафиксировать runtime, зависимости и тестовые изображения.

Для локального пакетного эксперимента. CLI интересен как способ посмотреть, как несколько Squoosh-кодеков можно запускать через один интерфейс и один worker pool. Нулевой тариф и открытая лицензия подходят для учебного или исследовательского стенда без требования долгосрочной поддержки.

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

Для разработчика, которому важна локальная обработка. CLI не отправляет изображения в облако во время кодирования, поэтому исходники остаются в файловой системе компьютера. При этом зависимости всё равно нужно получить через npm или подготовить заранее.

Кому не подойдёт

Для нового production-проекта на современном Node.js. Замороженный engines и прекращённое сопровождение делают пакет слабой основой для нового автоматизированного конвейера. Современный проект выиграет от поддерживаемого инструмента с актуальными runtime-требованиями.

Для фотографа, которому нужен визуальный редактор. Здесь нет сравнения до/после, ползунка качества, зума и превью. Для ручного подбора компрессии веб-версия Squoosh соответствует задаче лучше.

Для сложной древовидной медиатеки. Встроенной рекурсии и сохранения структуры каталогов нет. При тысячах файлов с повторяющимися именами потребуется дополнительная логика вокруг CLI.

Для RAW, TIFF, HEIC, SVG и GIF как универсального конвертера. Squoosh CLI не является всеформатным графическим комбайном. Если входной парк файлов шире набора его декодеров, практичнее ImageMagick, Sharp или специализированные инструменты.

Для сервера с жёстким лимитом CPU. CLI сам выбирает число workers по CPU и не предоставляет простой опции concurrency. Когда нагрузку нужно точно дозировать, этот механизм неудобен.

Альтернативы Squoosh CLI

Squoosh в браузере

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

ImageMagick

ImageMagick — активно используемый набор командных инструментов для преобразования изображений. Команда magick умеет конвертацию форматов, resize, crop, поворот и множество других операций. По сравнению с Squoosh CLI это существенно более широкий универсальный инструментарий. Он лучше подходит, если входы разнообразны, нужна сложная обработка или важна долгосрочная командная инфраструктура, а не именно исторический набор Squoosh-кодеков.

Sharp

Sharp — современный модуль обработки изображений для JavaScript, построенный вокруг libvips. В актуальной документации он ориентирован на Node.js 20.9 и новее, а также поддерживает современные JavaScript-среды с Node-API. Он читает распространённые JPEG, PNG, WebP, AVIF, GIF, SVG и TIFF и создаёт веб-форматы программно. В отличие от Squoosh CLI, Sharp в первую очередь библиотека: для автоматизации нужно написать небольшой JavaScript-код, зато API удобнее встраивается в текущий backend или build pipeline.

cwebp

Если задача сводится к созданию WebP, специализированный cwebp проще по архитектуре. Официальная утилита Google принимает, в частности, PNG, JPEG и TIFF и выдаёт WebP. У неё есть параметры качества, lossless, resize, crop и многопоточность. Она не заменяет Squoosh CLI как мультиформатный комбайн, зато исключает лишний слой Node.js и WebAssembly, когда нужен только WebP.

avifenc из libavif

Для AVIF прямой альтернативой является avifenc из проекта libavif. Это специализированная утилита кодирования AVIF. Проект продолжает выпускать обновления; в мае 2026 года опубликован релиз libavif 1.4.2. Такой выбор разумнее, когда нужен именно AVIF, важен текущий нативный энкодер и не требуется единый интерфейс сразу к MozJPEG, WebP, JPEG XL и другим кодекам.

Частые проблемы и диагностика

npx или squoosh-cli не запускается на современном Node.js

Сначала нужно вывести фактическую версию Node.js и сравнить её с engines пакета. Для 0.7.3 заявлены только ветки 12.20.2+, 14.13.1+ и 16.x. Ошибка на Node 18, 20 или более новой ветке не должна автоматически трактоваться как повреждённое изображение: runtime уже находится за пределами объявленной совместимости.

Особенно характерны сообщения, где фигурируют WebAssembly-файлы и ошибки URL. В трекере Squoosh есть случай на Node.js 18 с ошибкой разбора URL к локальному wasm-файлу. Поскольку CLI больше не сопровождается, надёжнее либо воспроизводить его в изолированной совместимой среде, либо мигрировать на поддерживаемый инструмент, чем строить новый production-процесс на случайных патчах старой зависимости.

Конфигурация кодека не разбирается

CLI передаёт строку конфигурации в JSON5.parse. Поэтому нужно проверить две вещи: корректен ли сам объект и сохранила ли командная оболочка кавычки до передачи Node-процессу. Если одна и та же строка работает в одной оболочке и ломается в другой, причина часто находится не в кодеке, а в правилах quoting.

Для диагностики полезно начать с пустого объекта конкретного энкодера или с documented auto, убедиться, что файл кодируется, и затем добавлять параметры. Это отделяет ошибку синтаксиса от ошибки декодирования или несовместимого runtime.

Файл не декодируется

Нужно проверить фактический формат файла, а не только расширение. У Squoosh CLI нет универсального декодера для всех изображений. GIF и SVG не поддерживаются как входы, а RAW, TIFF и HEIC не входят в опубликованный набор декодеров @squoosh/lib 0.4.0. Если известный корректный JPEG или PNG обрабатывается, а конкретный файл нет, проблема, скорее всего, связана с форматом или содержимым этого файла.

Повреждённый файл также может завершить декодирование ошибкой. CLI не является средством восстановления изображений, поэтому исправление битой структуры находится вне его назначения.

Обработались не все файлы из папки

Следует проверить вложенность. Программа берёт только файлы первого уровня переданного каталога; подпапки не обходятся. Если в корне лежит 20 файлов, а ещё 200 распределены по вложенным папкам, встроенный каталоговый режим увидит только 20 верхнеуровневых файлов.

После этого стоит проверить расширения и ошибки декодирования. Количество результатов должно сопоставляться не со всем деревом каталога, а с числом реально переданных и успешно декодированных входов.

Результат оказался больше оригинала

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

Такой файл не следует автоматически публиковать вместо оригинала только потому, что он прошёл Squoosh CLI. Нужно сравнить качество, форматную необходимость и фактический размер. Если новый вариант не даёт пользы, его можно не использовать.

Оригинал неожиданно изменился

Нужно сопоставить input, output-dir, suffix и расширение энкодера. Если исходный PNG был обработан OxiPNG в текущий каталог с пустым suffix, путь результата мог совпасть с путём оригинала. Для дальнейшей работы следует отделять source и output либо всегда применять отличающий суффикс.

Восстановить уже перезаписанный оригинал Squoosh CLI не может: автоматического backup в коде нет. Поэтому защита должна быть организована до запуска.

Один результат заменил другой при обработке разных папок

Причина может быть в одинаковом basename. CLI отбрасывает структуру каталога при построении имени результата. Если два входа имеют одинаковое имя без расширения и кодируются в один формат в общий output-dir, итоговый путь совпадёт. Решение — заранее обеспечить уникальные имена, использовать разные output-dir или разделить запуски.

Процесс долго остаётся на Encoding

Проектный трекер содержит исторические сообщения о зависании пакетной обработки. Универсального исправления в поддерживаемой новой версии CLI нет, поскольку сопровождение прекращено. Перед выводом о «медленном кодеке» нужно проверить runtime, один одиночный тестовый файл, затем небольшой пакет и только потом большой набор.

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

CPU загружен сильнее ожидаемого

Это соответствует реализации: ImagePool создаётся на cpus().length. Снижение числа workers через стандартный флаг Squoosh CLI не предусмотрено. На общем сервере процесс лучше запускать в инфраструктуре, где CPU можно ограничить внешними средствами, либо заменить инструмент на тот, где concurrency задаётся штатно.

Как проверить результат после обработки

У Squoosh CLI нет собственного окна проверки, поэтому контроль стоит разделить на технический и визуальный. Техническая часть отвечает на вопрос, созданы ли нужные файлы и соответствуют ли они задаче; визуальная — не стало ли изображение неприемлемым после компрессии.

1. Проверьте число выходов. Для каждого исходника должно быть столько файлов, сколько энкодеров было реально включено, если кодирование завершилось без ошибки.
2. Сверьте каталог и имена. Убедитесь, что файлы находятся в output-dir, suffix применён, а одинаковые basename не привели к коллизии.
3. Сравните размер. Используйте итоговый процент Squoosh results как быстрый индикатор, но не как оценку качества.
4. Проверьте геометрию. После resize откройте метаданные готового файла внешним средством и убедитесь, что ширина и высота соответствуют ожидаемым.
5. Откройте каждый целевой формат. Проверка должна проходить в том браузере, приложении или цепочке публикации, где файл реально будет использоваться.
6. Посмотрите сложные участки. Увеличьте тонкие линии, текст, мелкие детали, полупрозрачные края и градиенты; именно там артефакты компрессии заметнее всего.
7. Сохраните оригинал. Производный web-файл не должен становиться единственной копией исходной фотографии.

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

FAQ

Squoosh CLI всё ещё можно установить?

Да. Пакет @squoosh/cli 0.7.3 остаётся опубликованным в npm. Но он больше не поддерживается активно, поэтому факт доступности пакета не следует трактовать как актуальность его runtime и исправление ошибок.

Какая версия Squoosh CLI является последней опубликованной?

В npm последней опубликованной версией @squoosh/cli остаётся 0.7.3 от 3 января 2023 года. Это именно тот пакет, для которого в package.json зафиксированы старые ветки Node.js 12, 14 и 16.

Нужен ли аккаунт Google?

Нет. CLI запускается как npm-пакет и не использует вход в Google-аккаунт как условие кодирования. В нём нет личного кабинета, лимита изображений по учётной записи или облачного тарифа.

Отправляет ли Squoosh CLI фотографии в интернет?

Обработка в опубликованном исходном коде CLI локальная: файл читается с диска, кодируется в ImagePool и записывается на диск. Сеть может понадобиться npm или npx для получения самого пакета и зависимостей, но это отдельный этап установки.

Можно ли одной командой получить WebP и AVIF?

Да. CLI позволяет включить несколько энкодеров одновременно. После одной стадии декодирования и общей предварительной обработки создаются выходы каждого выбранного формата.

Можно ли передать целую папку?

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

Можно ли ограничить количество потоков?

В стандартных опциях Squoosh CLI 0.7.3 такого параметра нет. Код создаёт ImagePool с числом workers, равным количеству CPU-ядер, доступных Node.js.

Есть ли русский интерфейс?

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

Поддерживает ли CLI GIF и SVG?

Нет, эти форматы не входят в поддерживаемые входы Squoosh CLI 0.7.3. Для них лучше выбрать инструмент с соответствующим декодером.

Заменяет ли auto ручную проверку качества?

Нет. Auto ориентируется на целевую Butteraugli distance и остаётся экспериментальным механизмом. Он не знает требований конкретного сайта к мелкому тексту, фирменной графике или критичным деталям фотографии, поэтому визуальная проверка нужна отдельно.

Почему размер в CLI может отличаться от результата современного Squoosh в браузере?

CLI заморожен на старой версии пакета и его зависимостей, тогда как веб-приложение продолжило развиваться. Общая историческая основа кодеков не означает, что текущая браузерная версия и @squoosh/cli 0.7.3 обязаны выдавать одинаковый бинарный результат при похожих настройках.

Можно ли использовать Squoosh CLI в CI?

Технически CLI и создавался с расчётом на автоматизацию, но для нового CI в 2026 году главным препятствием остаётся неподдерживаемый пакет и старый диапазон Node.js. В существующем зафиксированном pipeline он может продолжать воспроизводиться; для нового процесса практичнее поддерживаемая альтернатива.

Есть ли ограничение на число изображений?

Документация 0.7.3 не задаёт числового лимита количества файлов. Практическая граница определяется ресурсами среды и тем, что CLI читает и декодирует набор параллельно. На очень больших партиях важнее наблюдать за памятью и временем, чем искать несуществующую тарифную квоту.

Сохраняет ли программа структуру исходных папок?

Нет. Результат строится в указанном output-dir по базовому имени файла. Поэтому одинаковые имена из разных каталогов требуют отдельной защиты от коллизии.

Итог

Squoosh CLI остаётся интересным примером того, как набор WebAssembly-кодеков Squoosh был превращён в пакетный Node.js-инструмент. Для исторического или строго зафиксированного процесса он способен выполнять полезную работу: локально менять размер, сокращать палитру, поворачивать изображения, параллельно кодировать несколько файлов и за один запуск создавать JPEG, PNG, WebP, AVIF, JPEG XL и WebP2.

Для нового проекта решающим фактором становится не ширина списка кодеков, а жизненный цикл. @squoosh/cli 0.7.3 не поддерживается, требует старых веток Node.js и не получил адаптации к современной среде. Если задача — вручную подобрать качество нескольких фотографий, рациональнее актуальный Squoosh в браузере. Если нужен универсальный поддерживаемый CLI, практичнее ImageMagick. Для современного JavaScript-пайплайна подходит Sharp, а для узкой конвертации в WebP или AVIF — cwebp и avifenc соответственно.

Использовать Squoosh CLI сегодня имеет смысл там, где уже есть совместимая изолированная среда и важна воспроизводимость старой конфигурации. В таком случае критичны три правила: не запускать обработку важных оригиналов в каталог с совпадающими выходными именами, учитывать нерекурсивную работу с папками и проверять качество готовых файлов вне терминала. Без этих условий преимущества пакетной автоматизации легко перекрываются риском перезаписи и проблемами совместимости.