
Squoosh CLI — консольная утилита для повторяемой оптимизации изображений: она принимает файлы, применяет изменение размера или палитры, затем запускает выбранный кодек и пишет результат на диск. Для знакомства с программой можно скачать Squoosh CLI бесплатно, но перед внедрением в рабочую сборку важно учитывать статус пакета: исходный @squoosh/cli в npm помечен как больше не поддерживаемый. Поэтому этот материал строится вокруг воспроизводимых команд, проверки результата и безопасного применения в уже существующих процессах.
Главное отличие от браузерного Squoosh — отсутствие визуального холста и ползунков. Здесь рабочая область — терминал, а интерфейсом служат параметры команды: что читать, какую операцию выполнить, каким кодеком записать файл, куда поместить результат и какой суффикс добавить. Такой подход удобен разработчикам, контент-командам и техническим специалистам, которым нужно обработать десятки или сотни изображений одинаковым способом, а не вручную настраивать каждый файл.
Что представляет собой Squoosh CLI и как устроен его интерфейс
Squoosh CLI переносит основные операции проекта Squoosh в командную строку. Пакет умеет изменять размер, уменьшать число цветов, поворачивать изображение и запускать несколько кодеков: MozJPEG, WebP, AVIF и OxiPNG. При этом консольная версия не показывает интерактивное сравнение «до/после», поэтому роль контроля качества переходит к просмотру готового файла и анализу отчёта о размере. Для ручного подбора параметров проще использовать веб-версию Squoosh, а затем переносить понятные настройки в повторяемую команду.

Кому и для каких задач нужна консольная версия
Утилита полезна там, где важна одинаковая обработка большого набора ресурсов: изображения для сайта перед сборкой, иллюстрации документации, скриншоты продукта, карточки каталога, превью, наборы иконок. Сценарий начинается не с ручного открытия файла, а с каталога и правила: например, все JPEG шире нужного размера уменьшить до заданной ширины и создать WebP-копии. Команда после этого становится частью npm script, CI-задачи или локальной процедуры подготовки контента.
Для единичной фотографии практичнее веб-приложение с предпросмотром. Консольная версия раскрывается в повторяемых сериях: одна команда применяется к новым файлам, а параметры сохраняются в проекте и не зависят от ручных настроек сотрудника.
Карта командной строки: вход, операции, кодек и вывод
Базовую строку удобно читать слева направо. Сначала идёт npx @squoosh/cli или установленная команда squoosh-cli. Затем — общие параметры, например каталог результата и суффикс имени. После них задаются предварительные операции: --resize, --quant, --rotate. Далее выбирается один или несколько кодеков: --mozjpeg, --webp, --avif, --oxipng и другие, перечисленные в справке. В конце указывается один файл или набор файлов. Порядок полезно сохранять одинаковым во всех скриптах, даже когда парсер принимает иной вариант: так команду проще проверять и сопровождать.
Отдельный экран настроек в Squoosh CLI отсутствует. Справка --help выполняет роль карты интерфейса, --version сообщает версию пакета, терминал показывает прогресс и блок Squoosh results, а файловая система становится областью экспорта. Именно поэтому перед любым пакетным запуском стоит проверять текущий каталог, маску файлов и папку назначения. Ошибка в этих трёх местах встречается чаще, чем ошибка самого кодека.
Статус пакета и ограничения, которые влияют на работу
В npm исходный пакет @squoosh/cli опубликован как версия 0.7.3 и помечен сообщением Project no longer maintained. Это не делает старые команды автоматически бесполезными, но меняет подход к эксплуатации. Утилиту разумно считать зафиксированным инструментом для совместимой среды, а не активно развиваемой платформой. В новых проектах сначала проверяют запуск на используемой версии Node.js, затем закрепляют рабочее окружение и только после этого добавляют обработку в сборку.
В архиве issues проекта есть отчёты о сбоях с отдельными версиями Node.js, WebAssembly и некоторыми сочетаниями параметров. Поэтому здесь не приводится выдуманная таблица «поддерживаемых ОС и Node.js»: исходный пакет не поддерживается, а публичные сообщения показывают, что совместимость зависит от конкретной среды. Практическая защита — тестовая команда на одном файле, фиксация версии окружения в проекте и проверка выходного изображения после обновлений.
Как пользоваться Squoosh CLI: от первой команды до пакетной обработки
Работу лучше строить от минимальной команды к сложной. Сначала убедитесь, что терминал видит Node.js и npx, затем получите справку Squoosh CLI, обработайте один тестовый файл, проверьте созданный результат и только после этого расширяйте маску до каталога. Такой порядок отделяет проблемы установки от ошибок в параметрах кодека и от неправильного выбора входных файлов.

wh王涵 / CSDN, CC BY-SA 4.0
Шаг 1. Проверить запуск через npx и прочитать справку
Для исходного npm-пакета самый безопасный старт — одноразовый запуск через npx: он не требует глобально добавлять команду в систему. Выполните npx @squoosh/cli --help. В корректной среде терминал выводит список общих параметров и кодеков. Затем выполните npx @squoosh/cli --version и сохраните версию вместе с версией Node.js в технической заметке проекта. Это особенно важно для старого пакета, потому что будущая смена Node.js способна повлиять на запуск WebAssembly-модулей.
- Откройте терминал в каталоге проекта, где лежит тестовое изображение. Не начинайте с папки, содержащей тысячи файлов.
- Проверьте Node.js: выполните node --version. Значение нужно не для сравнения с выдуманным «минимумом», а для фиксации реально работающего окружения.
- Откройте справку: npx @squoosh/cli --help. Убедитесь, что в выводе присутствуют --output-dir, --suffix, --resize, --quant, --rotate и нужный кодек.
- Проверьте пакет: npx @squoosh/cli --version. Если команда падает до вывода справки, не переходите к обработке файлов: сначала устраните проблему среды.
- Создайте резервную копию теста или работайте с копией исходного изображения. Для первого запуска используйте отдельный каталог результата.
На Windows удобнее запускать примеры в PowerShell, а на macOS и Linux — в привычной оболочке. Конфигурации кодеков передаются строкой, поэтому правила кавычек оболочки имеют значение. В PowerShell и Bash/zsh объект в одинарных кавычках читается предсказуемо; в cmd.exe кавычки приходится экранировать иначе. Если команда выглядит правильно, но CLI сообщает об ошибке разбора конфигурации, сначала перенесите тот же запуск в PowerShell или Bash, а не меняйте параметры кодека наугад.
Шаг 2. Сжать один файл и понять модель кодеков
Начните с формата, который соответствует задаче. Для JPEG-фотографии можно получить WebP-копию, для PNG-графики — оптимизированный PNG через OxiPNG, а для проверки AVIF — отдельный AVIF-файл. У Squoosh CLI выбор кодека одновременно определяет расширение результата. Поэтому команда не «перезаписывает JPEG как JPEG» по умолчанию: если вы активировали --webp, итогом будет WebP, а если --mozjpeg — JPEG.
- WebP с явным качеством: npx @squoosh/cli --webp '{"quality":75}' image.jpg. После завершения рядом с исходником должен появиться файл .webp, если каталог вывода не переопределён.
- MozJPEG: npx @squoosh/cli --mozjpeg '{"quality":75}' image.jpg. Используйте этот вариант, когда нужен именно JPEG и вы хотите управлять качеством кодера.
- AVIF через автооптимизацию: npx @squoosh/cli --avif auto image.jpg. Auto-режим экспериментальный, поэтому после него особенно важна визуальная проверка.
- OxiPNG: npx @squoosh/cli --oxipng '{"level":2}' image.png. Такой запуск предназначен для PNG и использует уровень оптимизации OxiPNG.
- Проверка результата: откройте созданный файл в просмотрщике или браузере, сравните мелкие детали, градиенты, тонкие линии, прозрачность и текст с исходником, затем сверяйте размер.
Не сравнивайте кодеки только по проценту экономии. Потеря веса за счёт уменьшения разрешения — совсем другая операция, чем кодирование того же количества пикселей. Сначала определите требуемые размеры, затем настройте кодек. Для общего понимания конвертации между растровыми форматами пригодится руководство по преобразованию JPG, PNG, WebP, HEIC и TIFF.
Шаг 3. Изменить размер перед кодированием
Изменение размера выполняется до кодирования. В параметре --resize передаётся объект с шириной, высотой и методом ресэмплинга. Для типичной задачи «уменьшить до ширины 1280 пикселей» достаточно задать width и затем выбранный формат вывода. Не пытайтесь одновременно решать кадрирование, изменение пропорций и сжатие, пока не проверили, как конкретная конфигурация ведёт себя на тестовом файле: у старой CLI были отдельные ошибки вокруг fitMethod.
- Возьмите копию большого изображения и заранее запишите его исходные размеры.
- Запустите изменение ширины и WebP: npx @squoosh/cli --resize '{"width":1280}' --webp auto image.jpg.
- Откройте результат и проверьте фактическую ширину в свойствах файла или через инструмент, которому доверяете.
- Проверьте геометрию: лица, круглые объекты и логотипы не должны стать растянутыми. Если пропорции изменились, не продолжайте пакетный запуск.
- Только после проверки одного файла переносите ту же конфигурацию на набор изображений.
Параметр --resize удобен именно в цепочке. Один запуск может уменьшить исходник и сразу создать WebP либо MozJPEG. Это экономит отдельный проход по файлам и уменьшает вероятность, что разные этапы будут выполнены с разными размерами. Но эта же связность повышает цену ошибки: неверная ширина применится ко всему набору. Поэтому тестовый файл и отдельный каталог вывода — обязательная часть практического процесса, а не перестраховка.
Шаг 4. Уменьшить палитру у графики и скриншотов
Параметр --quant сокращает число используемых цветов. Он особенно полезен для интерфейсных скриншотов, простых иллюстраций, схем и другой графики с ограниченной палитрой. Для фотографий агрессивное уменьшение числа цветов обычно проявляется постеризацией на градиентах, небе и коже. Поэтому --quant стоит воспринимать как отдельную оптимизацию, которую применяют только после просмотра типичных файлов.
- Подберите показательный PNG с теми же градиентами, тенями и прозрачностью, что встречаются в реальных материалах.
- Сначала запустите кодек без quant и сохраните размер и внешний вид как базовую точку.
- Добавьте --quant с объектом конфигурации, где numColors ограничивает палитру, а dither управляет распределением ошибки. Для старого CLI безопаснее начинать с умеренного ограничения, а не с экстремально малого числа цветов.
- Увеличьте результат и проверьте плавные переходы, края текста, полупрозрачные тени и тонкие линии.
- Сравните выигрыш в байтах с визуальными потерями. Если уменьшение размера невелико, уберите quant и оставьте только кодирование.
При подготовке PNG важно не путать два подхода: уменьшение палитры потенциально меняет пиксели, а OxiPNG выполняет оптимизацию PNG без необходимости превращать полноцветный исходник в палитровый. Для задач, где требуется сохранить прозрачность и структуру PNG без заметных изменений, полезно отдельно свериться с инструкцией по сжатию PNG с сохранением прозрачности.
Шаг 5. Обработать набор файлов и отправить результат в отдельную папку
После одиночного теста переходите к пакету. Squoosh CLI принимает несколько файлов и использует пул рабочих потоков для параллельной обработки. Общий параметр -d или --output-dir задаёт каталог результатов, а -s или --suffix добавляет суффикс к имени. Эти два параметра особенно полезны для безопасной первой серии: исходники остаются на месте, а обработанные версии легко отличить и удалить при неудачной конфигурации.

- Создайте каталог назначения, например dist-images, и убедитесь, что он не совпадает с папкой исходников.
- Проверьте маску оболочки: сначала выведите список файлов штатной командой оболочки или временно используйте два конкретных имени. Не допускайте попадания каталогов в список входов.
- Запустите пакет: npx @squoosh/cli --webp auto -d dist-images images/*.jpg. В Bash/zsh маску разворачивает оболочка; в других средах поведение может отличаться, поэтому ориентируйтесь на фактический список входных файлов.
- Добавьте суффикс при необходимости: --suffix _optimized позволяет получить предсказуемые имена и не смешивать версии при нескольких проходах.
- После завершения сравните количество файлов в исходной и выходной папке. Разница должна быть объяснима: только ожидаемые форматы и только те файлы, которые входили в маску.
- Выберите несколько крайних примеров — самый большой файл, изображение с прозрачностью, мелким текстом и градиентом — и просмотрите их вручную.
Документированный случай issue #916 показывает, что пакетная команда способна наткнуться на EISDIR, когда в набор входов попадает каталог. Практический вывод простой: не считайте маску «очевидной». Перед запуском на большом дереве всегда проверяйте, что она возвращает только файлы ожидаемого типа. Если нужна рекурсивная обработка сложной структуры, надёжнее сформировать список файлов внешним скриптом и передавать CLI уже проверенные пути.
Шаг 6. Прочитать Squoosh results и проверить, что оптимизация действительно полезна
После кодирования CLI выводит блок Squoosh results. В нём видно имя исходника, размер и созданные версии с процентным отношением к исходному файлу. Этот отчёт нужен для быстрой диагностики, но его нельзя превращать в единственный критерий качества. Даже идеальная экономия бессмысленна, если мелкий текст распался, прозрачность изменилась или цветные градиенты получили полосы.
- Зафиксируйте размер исходника и размер результата из отчёта.
- Проверьте расширение результата. Оно должно соответствовать выбранному кодеку, а не ожиданиям по имени исходного файла.
- Откройте изображение в масштабе 100% и отдельно посмотрите критичные зоны: волосы, траву, фактуру ткани, мелкий текст, градиенты, прозрачные края.
- Просмотрите уменьшенную версию в том размере, в котором она реально используется на сайте. Иногда артефакты, заметные при сильном увеличении, несущественны в рабочем размере; иногда наоборот — текст становится нечитаемым.
- Сравните несколько значений качества только на одном и том же исходнике и одинаковых размерах. Так вы отделите влияние кодека от влияния ресайза.
- Сохраните выбранную команду в проекте после проверки, а не в истории терминала. Это превращает ручной эксперимент в воспроизводимый процесс.
Как настроить качество и встроить Squoosh CLI в рабочий процесс
После базового запуска задача меняется: теперь нужно сделать результат повторяемым. Качество задаётся либо явной конфигурацией конкретного кодека, либо экспериментальным auto-режимом. Производительность зависит от числа файлов и параллельной работы, а надёжность — от того, насколько аккуратно вы разделяете исходники и результат, фиксируете среду и проверяете типовые изображения.

Шаг 1. Понять auto-режим и Butteraugli
В Squoosh CLI строка auto вместо объекта конфигурации активирует экспериментальную автооптимизацию. Она пытается уменьшать файл, ориентируясь на целевое расстояние Butteraugli. В справке исходного пакета доступны --max-optimizer-rounds и --optimizer-butteraugli-target; npm указывает значения по умолчанию 6 и 1.4 соответственно. Чем выше целевая дистанция, тем больше визуальных искажений допускает оптимизатор, поэтому увеличивать её ради меньшего файла без просмотра результата нельзя.
- Начните со стандартного auto: npx @squoosh/cli --webp auto image.jpg. Не меняйте одновременно Butteraugli и размеры изображения.
- Сохраните результат и визуально сравните его с исходником на критичных деталях.
- Если нужно исследовать границу сжатия, изменяйте только один параметр за проход. Например, оставьте размеры и кодек неизменными и сравните два значения целевой дистанции.
- Не делайте вывод по одному файлу. Проверьте фотографию, интерфейсный скриншот и иллюстрацию, если все три типа встречаются в проекте.
- После выбора режима закрепите параметры в npm script или скрипте сборки. Автоматизация должна повторять уже проверенное решение, а не подбирать качество заново на продакшен-сборке.
Auto удобен для первичного поиска баланса, но не заменяет спецификацию качества. В проектах с жёсткими требованиями к брендингу, интерфейсным скриншотам или тексту полезнее использовать явные параметры и тестовый набор эталонных изображений. Тогда изменение результата после обновления окружения заметно сразу.
Шаг 2. Использовать явное качество WebP и MozJPEG
Явная конфигурация делает команду понятнее: в WebP и MozJPEG можно задать quality, не трогая остальные параметры, и CLI подставит для них значения по умолчанию из набора кодека. Это лучше, чем копировать длинный объект без понимания каждого поля. Чем короче конфигурация, тем меньше вероятность случайно зафиксировать устаревший или нежелательный параметр.
- Создайте два результата WebP с разным quality, например 75 и 85, на одном тестовом JPEG. Команды отличаются только числом quality.
- Сравните файл в одинаковом масштабе, особенно области с мелкой фактурой и плавными цветовыми переходами.
- Повторите тот же принцип для MozJPEG, когда нужен JPEG: меняйте только quality, не смешивая эксперимент с resize и quant.
- Выберите нижнее значение, которое проходит визуальную проверку на типовых материалах. Не переносите одно значение между разными кодеками как будто шкалы эквивалентны.
- Зафиксируйте команду и тестовые исходники. При изменении версии среды повторите сравнение на том же наборе.
Для JPEG полезно дополнительно понимать разницу между «меньше файл» и «без потерь». Обычный MozJPEG в этом сценарии использует сжатие с потерями, и повышение quality уменьшает степень потерь, но не превращает процесс в безусловно идентичное пиксельное копирование. Практические ориентиры по компромиссам JPEG собраны в материале о сжатии JPEG.
Шаг 3. Создать несколько размеров через суффиксы и отдельные проходы
Squoosh CLI не нужно заставлять решать генерацию всей responsive-матрицы одной гигантской командой. Надёжнее выполнить несколько понятных проходов с разной шириной и суффиксом. Так имена файлов сохраняют связь с назначением, а ошибочный вариант можно удалить независимо. Например, один проход создаёт версию шириной 1280 пикселей с суффиксом -1280, другой — 640 пикселей с -640.
- Определите реальные точки использования в интерфейсе сайта. Не генерируйте десятки размеров «на всякий случай».
- Для большого варианта выполните команду с --resize '{"width":1280}', выбранным кодеком, --suffix _1280 и отдельной папкой результата.
- Для малого варианта повторите запуск с шириной 640 и суффиксом _640.
- Проверьте имена. У каждой исходной картинки должны появиться ожидаемые варианты без перезаписи друг друга.
- Сравните визуальное качество каждого размера отдельно. Малый файл может выдержать более сильное сжатие, но это нужно проверять, а не предполагать.
- Добавляйте варианты на сайт только после проверки фактических размеров и расширений.
Такая схема проще для отладки и кэша: по имени видно назначение файла. Она также не зависит от наличия специальной функции пресетов внутри Squoosh CLI. Пресетом становится сама команда, сохранённая в скрипте проекта.
Шаг 4. Сохранить команды в npm scripts и отделить исходники от сборки
Для Node.js-проекта удобно хранить проверенные команды в package.json как npm scripts. Смысл не в том, чтобы спрятать длинную строку, а в том, чтобы сделать способ обработки единым для команды. Скрипт должен читать исходники из стабильного каталога и писать только в производную папку, которую можно удалить и собрать заново.
- Выберите структуру каталогов: например, src/images для исходников и dist/images для производных файлов.
- Создайте один сценарий на одну задачу. Отдельно WebP для фотографий, отдельно OxiPNG для PNG, отдельно responsive-размеры. Не объединяйте разные правила без необходимости.
- Впишите в npm script уже проверенную команду с -d dist/images. Не экспериментируйте с качеством внутри основного скрипта.
- Запустите сценарий на маленьком наборе и убедитесь, что повторный запуск даёт предсказуемые имена и не затрагивает src/images.
- Добавьте проверку количества и типа выходных файлов в свою сборку или CI, если изображения критичны для релиза.
- Зафиксируйте версию Node.js средствами проекта и не обновляйте её в той же операции, где меняете параметры изображений. Так проще понять причину регрессии.
Оригинальный Squoosh CLI использует пул рабочих потоков и может обрабатывать несколько изображений параллельно. Это полезно для сборки, но означает, что большой пакет потребляет заметно больше памяти, чем единичный файл. В issue #1012 описана проблема выделения памяти при обработке примерно двух сотен изображений. Поэтому большие архивы лучше делить на разумные порции и наблюдать за стабильностью процесса, а не увеличивать параллелизм вслепую.
Шаг 5. Сверить параметры с визуальным интерфейсом Squoosh
Хотя консольная версия самостоятельна, веб-Squoosh остаётся удобным стендом для понимания того, как выглядят кодеки и ресайз. В браузере сразу видны изображение, размер результата и панель параметров. Для старого проекта Squoosh существовал механизм Copy npx command, но архив issues содержит сообщения о проблемах с сгенерированной строкой, поэтому такую команду нужно воспринимать как исходную заготовку и проверять в своей оболочке.



- Откройте типовой исходник в веб-Squoosh и подберите визуально приемлемый кодек.
- Запишите только понятные параметры, которые действительно хотите перенести в автоматизацию: размер, качество, число цветов.
- Соберите короткую CLI-команду вручную вместо бездумного копирования длинного объекта со всеми полями.
- Запустите CLI на том же исходнике и сравните размер и внешний вид результата.
- При расхождении не считайте веб и CLI полностью идентичными. В архиве проекта есть закрытые сообщения о разном размере результата при похожих настройках. Для рабочего процесса эталоном должен быть фактический файл, создаваемый вашей зафиксированной командой.
Шаг 6. Настроить практический контроль качества перед публикацией
Автоматизация полезна только вместе с контролем. Минимальная проверка состоит из трёх слоёв: технического, визуального и интеграционного. Технический подтверждает размеры, формат и наличие файла. Визуальный ищет артефакты. Интеграционный проверяет, что сайт или приложение действительно использует нужный вариант и не растягивает его выше исходного разрешения.

- Технический слой: проверьте расширение, ширину и высоту, ненулевой размер файла и количество результатов.
- Визуальный слой: откройте несколько эталонных файлов на 100% и в реальном размере отображения. Ищите блоки, кольца вокруг контрастных границ, потерю мелких деталей, полосы в градиентах и проблемы прозрачности.
- Сравнительный слой: храните один исходник и один одобренный результат для каждого типа контента. После изменения окружения прогоняйте их снова.
- Интеграционный слой: откройте страницу или компонент, который использует изображение, и убедитесь, что браузер загружает ожидаемый формат и размер.
- Резервный слой: исходники не удаляются после оптимизации. Производная папка должна восстанавливаться из них полностью.
Для массовой публикации ориентируйтесь не на одну «магическую» настройку, а на классы контента. Фотографии, скриншоты интерфейса, логотипы и изображения с прозрачностью имеют разные слабые места. Одно значение качества, которое хорошо работает для пейзажей, способно заметно испортить мелкий текст или плоскую графику. Поэтому тестовый набор должен представлять реальные типы материалов проекта.
Как диагностировать и исправлять ошибки Squoosh CLI
Большинство проблем Squoosh CLI сводится к четырём причинам: устаревшая среда или, наоборот, слишком новая версия Node.js для старого пакета; некорректно переданная строка конфигурации; неверный набор входных путей; ожидание полной идентичности с веб-Squoosh. Утилита даёт достаточно информации для локализации ошибки, но не имеет современного мастера диагностики, поэтому полезно уменьшать сценарий до одного файла и одного кодека.

Типичные ошибки и порядок исправления
Первое правило диагностики — убрать всё лишнее. Если пакетный запуск не работает, не меняйте одновременно Node.js, кавычки, кодек и маску. Выполните --help. Затем один кодек на одном файле без resize. После успешного результата возвращайте параметры по одному. Такой двоичный поиск быстрее, чем попытка угадать причину по последней строке большого стека.
- CLI не запускается или падает при загрузке модулей. Зафиксируйте node --version и версию @squoosh/cli, повторите минимальный --help. Для исходного пакета существуют документированные отчёты об ошибках WebAssembly и URL на отдельных версиях Node.js, поэтому рабочую среду лучше воспроизводить, а не обновлять вслепую.
- Ошибка JSON5 или конфигурации. Проверьте кавычки оболочки и сократите объект до одного параметра. В issue #1181 зафиксирован случай, когда команда, скопированная из веб-приложения, давала ошибку разбора.
- EISDIR или попытка прочитать каталог как файл. Проверьте, что маска отдаёт только файлы. Не передавайте корень дерева без фильтра.
- Процесс зависает на большом наборе. Разделите пакет на меньшие части, уберите повреждённые файлы и повторите один проблемный вход отдельно. Для старого CLI есть отчёты о зависаниях и памяти на больших сериях.
- Результат больше исходника. Это не всегда ошибка. Переход из lossy-формата в lossless или неоптимальная конфигурация может увеличить файл. Сравните назначение форматов и уберите бессмысленное перекодирование.
- Картинка выглядит иначе, чем в веб-Squoosh. Сравнивайте фактические параметры и помните, что в архиве проекта есть сообщения о расхождениях веб-версии и CLI. Для production используйте результат той команды, которая реально запускается в вашей среде.
Что делать с несовместимостью Node.js и старым пакетом
Так как @squoosh/cli больше не поддерживается, корректная стратегия — не искать «самую новую версию Node.js, которая обязана работать», а закрепить проверенную комбинацию проекта. В публичных issues есть пример ERR_INVALID_URL и ошибки загрузки wasm на Node 18.12.1, а также более старые сообщения о других сочетаниях среды. Эти отчёты не образуют официальную матрицу совместимости, поэтому нельзя превращать их в универсальное правило вроде «нужен Node N».
- Сначала воспроизведите проблему на одном файле и сохраните полный текст ошибки.
- Проверьте версии Node.js, npm и @squoosh/cli. Эти три значения нужны для воспроизводимости.
- Сверьте проблему с архивом issues по точному имени ошибки или модулю, а не по общему описанию «не работает».
- Если проект уже имеет рабочую среду, закрепите её через стандартный для команды менеджер версий или контейнер и не обновляйте без отдельного теста изображений.
- Для нового проекта оцените поддерживаемую альтернативу, если вам нужны долгосрочные обновления, современный Node.js и активное исправление ошибок.
Плюсы, минусы, альтернативы и итоговый выбор
После практической части важно оценить жизненный цикл инструмента: Squoosh CLI удобен в закреплённой рабочей среде, но исходный npm-пакет больше не сопровождается.

Сильные и слабые стороны
Squoosh CLI остаётся понятным примером того, как перенести качественные веб-кодеки в автоматизированный процесс, но его достоинства нужно оценивать вместе со статусом обслуживания. Для существующего проекта, где команда уже проверена, ценность может быть высокой; для новой инфраструктуры отсутствие поддержки становится существенным техническим долгом.
Плюсы
- Одна команда объединяет resize, quant, поворот и кодирование, поэтому типовой пайплайн получается компактным.
- Поддерживаются несколько полезных кодеков Squoosh: MozJPEG, WebP, AVIF и OxiPNG.
- Есть пакетная обработка и пул рабочих потоков, что удобнее ручной оптимизации десятков файлов.
- Параметры можно хранить в npm scripts и воспроизводить на новых наборах изображений.
- Есть отдельные параметры каталога вывода и суффикса, позволяющие безопасно отделять производные файлы от исходников.
- Исходный проект Squoosh открыт, а пакет распространяется под Apache-2.0.
Минусы
- Исходный @squoosh/cli больше не поддерживается, поэтому проблемы совместимости с современным окружением не получают гарантированных исправлений.
- Нет интерактивного предпросмотра, поэтому визуальную оценку приходится делать после записи результата.
- Строковые объекты конфигурации чувствительны к правилам кавычек конкретной оболочки.
- Архив issues содержит сообщения о различиях с веб-Squoosh, ошибках отдельных кодеков, памяти и зависаниях.
- Для сложной рекурсивной обработки дерева файлов удобнее внешний скрипт, который заранее формирует безопасный список входов.
- В новой инфраструктуре поддерживаемые специализированные инструменты часто дают более предсказуемый жизненный цикл.
Кому программа подходит, а кому лучше выбрать другой инструмент
Squoosh CLI подходит разработчику или технической команде, у которой уже есть проверенная команда и закреплённое окружение; небольшому сайту с регулярным пакетом изображений; проекту, где важно быстро получить WebP, AVIF, MozJPEG или оптимизированный PNG одной понятной утилитой; локальной автоматизации, которую не планируют переносить на постоянно обновляющиеся раннеры без тестирования.
Для нового долгоживущего CI-процесса лучше сразу оценивать активно поддерживаемые решения. Если задача сводится только к WebP, специализированный cwebp проще и прозрачнее. Для AVIF есть avifenc из libavif. Для lossless-оптимизации PNG — OxiPNG. Для Node.js-проекта с программной обработкой и современными форматами практичен Sharp. Для универсальной командной строки с широким набором преобразований подходит ImageMagick. На XeonLive отдельно разобран libavif и его инструменты AVIF.
Краткое сравнение с Sharp, cwebp, avifenc, OxiPNG и ImageMagick
Sharp — библиотека для Node.js, а не прямая копия Squoosh CLI. Она умеет писать JPEG, PNG, WebP, AVIF и другие форматы, изменять размер и возвращать метаданные результата. Её сильная сторона — программный API: правила можно выразить обычным JavaScript, добавить ветвление, проверку размеров и обработку ошибок без длинных строковых объектов.
cwebp — узкий командный кодер WebP. Он принимает JPEG, PNG или TIFF и создаёт WebP. Если весь процесс ограничен этим форматом, специализация упрощает диагностику: меньше уровней абстракции, яснее связь параметров с кодеком. avifenc выполняет аналогичную роль для AVIF: официальный libavif предоставляет отдельные консольные инструменты avifenc и avifdec, а современная документация описывает качество, скорость и число рабочих потоков.
OxiPNG — специализированный многопоточный оптимизатор PNG/APNG без потерь. Его удобно использовать, когда не требуется конвертация в другой формат или изменение размера. ImageMagick, наоборот, намного шире Squoosh CLI: он читает и преобразует множество форматов, умеет resize, crop, blur, композицию и другие операции. Такая универсальность полезна в сложных процессах, но требует собственной дисциплины настроек.
Если нужна подборка других инструментов для преобразования форматов, используйте рейтинг конвертеров изображений как карту вариантов, а затем проверяйте конкретный продукт под свой формат и сценарий.
Практические рекомендации по выбору сценария
- Нужно разово уменьшить одну картинку и глазами подобрать качество: используйте веб-Squoosh, потому что предпросмотр там важнее автоматизации.
- Есть существующий проект с рабочим @squoosh/cli: сохраните окружение, вынесите исходники и результат в разные каталоги, держите тестовый набор и не обновляйте Node.js без повторной проверки.
- Нужно обработать десятки фотографий одинаково: сначала проверьте один файл, затем пакет с --output-dir, после чего выборочно просмотрите крайние примеры.
- Новый Node.js-пайплайн должен жить годами: рассмотрите Sharp или специализированные кодеры, потому что исходный Squoosh CLI больше не сопровождается.
- Нужен только WebP: оцените cwebp. Нужен только AVIF: avifenc. Нужен lossless PNG: OxiPNG. Нужна широкая трансформация форматов: ImageMagick.
- Критично качество текста, интерфейсов и логотипов: не полагайтесь только на auto и проценты экономии. Создайте набор эталонных изображений и сравнивайте результат после каждого изменения команды или среды.
Можно ли ставить @squoosh/cli глобально?
Пакет поддерживал глобальную установку через npm, но для воспроизводимого проекта удобнее запуск через npx или зафиксированную зависимость. Исходный пакет больше не поддерживается, поэтому глобальная установка не решает вопросы совместимости среды.
Почему команда работает на одном компьютере и падает на другом?
Проверьте версии Node.js, npm и @squoosh/cli, а также оболочку, в которой разбираются кавычки конфигурации. У старого CLI есть документированные отчёты о проблемах WebAssembly и отдельных версиях Node.js.
Можно ли доверять auto без ручной проверки?
Нет. Auto-режим ориентируется на метрику и уменьшение файла, но итоговый материал всё равно нужно смотреть на реальных деталях, особенно на тексте, градиентах и прозрачности.
Почему оптимизированный файл иногда больше исходника?
Причина бывает в неподходящем формате, lossless-кодировании уже сжатого изображения, параметрах кодека или изменении структуры файла. Сначала сравните назначение входного и выходного формата, затем меняйте настройки.
Как безопасно запускать пакетную обработку?
Используйте отдельный каталог вывода, сначала проверьте маску входных файлов, обработайте небольшой набор, сравните число результатов и только затем запускайте всю коллекцию.
Что выбрать для нового проекта вместо Squoosh CLI?
Для Node.js-пайплайна практичен Sharp; для WebP — cwebp; для AVIF — avifenc; для PNG без потерь — OxiPNG; для широкого набора преобразований — ImageMagick. Выбор зависит от формата и требуемой автоматизации.
Итоговая логика работы с Squoosh CLI проста: сначала минимальный запуск и справка, затем один файл, потом понятные параметры качества и размера, после этого отдельная папка пакетного результата и обязательная визуальная проверка. Для существующей зафиксированной среды утилита остаётся удобной. Для новой инфраструктуры её статус «не поддерживается» следует учитывать как основной фактор выбора, а не как примечание в конце.