optimo

optimo

optimo 使用针对不同格式的压缩流水线来减小媒体文件的体积。

前置条件

optimo 会从 PATH 中查找压缩工具，若缺少必需的二进制文件，则会抛出错误。

各格式所需工具：

• 所有基于 ImageMagick 的格式：magick
• SVG 流水线：svgo
• JPEG 二次处理：mozjpegtran 或 jpegtran
• GIF 二次处理：gifsicle
• 视频流水线：ffmpeg

快速入门（CLI）

使用 npx 进行一次性运行：

npx -y optimo public/media

优化单个文件：

npx -y optimo public/media/banner.png

保留图像 EXIF 元数据：

npx -y optimo public/media/banner.jpg --preserve-exif # long version
npx -y optimo public/media/banner.jpg -p # short version

执行试运行（不更改文件）：

npx -y optimo public/media/banner.png --dry-run # long version
npx -y optimo public/media/banner.png -d # short version

启用有损模式：

npx -y optimo public/media/banner.jpg --lossy # long version
npx -y optimo public/media/banner.jpg -l # short version

转换并优化为新格式：

npx -y optimo public/media/banner.png --format jpeg # long version
npx -y optimo public/media/banner.png -f jpeg # short version

优化视频：

npx -y optimo public/media/clip.mp4

转换视频格式：

npx -y optimo public/media/clip.mov --format webm

将视频音轨静音（默认已静音）：

npx -y optimo public/media/clip.mp4 --mute # explicit true
npx -y optimo public/media/clip.mp4 --mute false # keep audio

按百分比调整尺寸：

npx -y optimo public/media/banner.png --resize 50% # long version
npx -y optimo public/media/banner.png -r 50% # short version

调整尺寸以达到目标最大文件大小（仅限图像）：

npx -y optimo public/media/banner.png --resize 100kB # long version
npx -y optimo public/media/banner.png -r 100kB # short version

按宽度调整尺寸：

npx -y optimo public/media/banner.png --resize w960 # long version
npx -y optimo public/media/banner.png -r w960 # short version

按高度调整尺寸：

npx -y optimo public/media/banner.png --resize h480 # long version
npx -y optimo public/media/banner.png -r h480 # short version

将优化后的图像输出为数据 URL（仅限单个图像文件）：

npx -y optimo public/media/banner.png --data-url # long version
npx -y optimo public/media/banner.png -u # short version

启用详细调试信息：

npx -y optimo public/media/banner.heic --dry-run --verbose # long version
npx -y optimo public/media/banner.heic -d -v # short version

流水线

optimo 会根据输出格式选择流水线：

• .png -> magick.png
• .svg -> svgo.svg
• .jpg/.jpeg -> magick.jpg/jpeg + mozjpegtran.jpg/jpeg（无损 JPEG 且不调整尺寸或转换时，会跳过 magick，仅运行 mozjpegtran）
• .gif -> magick.gif + gifsicle.gif
• 其他图像格式（webp、avif、heic、heif、jxl 等）-> magick.<format>
• 视频格式（mp4、m4v、mov、webm、mkv、avi、ogv）-> ffmpeg.<format>

模式行为：

• 默认：优先采用无损处理的流水线
• 图像默认会移除元数据/EXIF，以减小文件体积
• --lossy / -l：在支持的情况下执行有损 + 无损处理
• --mute / -m：移除视频音轨（默认值：true；传入 --mute false 可保留音频）
• --preserve-exif / -p：在输出中保留图像 EXIF 元数据

推荐工作流

1. 先使用 --dry-run 确认目标文件。
2. 先优化单个文件，再扩展到整个目录。
3. 仅在确实需要转换时使用 --format。
4. 仅在需要明确控制尺寸/大小时使用 --resize。
5. 对于视频，请注意不支持 --resize 100kB；请使用 50%、w960 或 h480。
6. 排查不受支持的文件或二进制文件/标志问题时，使用 --verbose。
7. 提交前，请在版本控制中检查输出。

CLI 选项

• -d、--dry-run：显示将进行的更改，但不写入文件。
• -f、--format：转换输出格式（jpeg、webp、avif 等）。
• -l、--lossy：启用有损 + 无损处理。
• -m、--mute：移除视频音轨（默认值：true；使用 --mute false 可保留音频）。
• -p、--preserve-exif：保留图像 EXIF 元数据（默认值：false）。
• -r、--resize：按百分比（50%）、最大文件大小（100kB，仅限图像）、宽度（w960）或高度（h480）调整尺寸。
• -s、--silent：隐藏逐文件日志。
• -u、--data-url：将优化后的图像作为数据 URL 返回（仅限单个图像文件）。
• -v、--verbose：打印调试日志（流水线选择、命令执行和错误）。

编程 API

const optimo = require('optimo')

await optimo.file('/absolute/path/image.jpg', {
  dryRun: false,
  lossy: false,
  preserveExif: false, // default
  format: 'webp',
  resize: '50%',
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  preserveExif: true, // keep EXIF metadata
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  resize: '100kB',
  onLogs: console.log
})

await optimo.file('/absolute/path/image.jpg', {
  resize: 'w960',
  onLogs: console.log
})

const { dataUrl } = await optimo.file('/absolute/path/image.png', {
  dataUrl: true,
  onLogs: console.log
})
// dataUrl is a base64 data URL string (images only, single file)

await optimo.file('/absolute/path/video.mp4', {
  lossy: false,
  mute: false, // true by default for videos
  format: 'webm',
  resize: 'w1280',
  onLogs: console.log
})

const result = await optimo.dir('/absolute/path/images')
console.log(result)
// { originalSize, optimizedSize, savings }

// Utility export
const { formatBytes } = require('optimo')
console.log(formatBytes(1024)) // '1 kB'

行为说明

• 非转换运行中，如果优化后的文件没有变小，则保留原始文件。
• 转换时，输出文件使用新的扩展名，并删除原始源文件（除非使用 --dry-run）。
• 目录模式下会跳过隐藏文件和文件夹（名称以 . 开头）。
• 不受支持的文件会标记为 [unsupported] 并忽略。
• 视频默认设置针对 Web 兼容性进行了优化（yuv420p，适用时使用快速启动 MP4）。
• 图像输出默认会移除 EXIF 元数据；使用 --preserve-exif 或 preserveExif: true 可保留。
• --data-url 仅支持单个图像文件（用于视频或目录模式时会抛出错误）。