
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 проста: сперва минимальный запуск и справка, затем один файл, потом понятные параметры качества и размера, после этого отдельная папка пакетного итога и обязательная визуальная проверка. Для существующей зафиксированной среды утилита остаётся удобной. Для новой инфраструктуры её статус «не поддерживается» нужно учитывать как основной фактор выбора, а не как примечание в конце.