optimize-assets-size

栅格图体积优化工具：在 JPEG / PNG / WebP / AVIF 间自动优选最小编码 / 自动重写 import 路径

直接写回源文件以减小 Git 体积（与 Vite 构建期 imagetools 等无关）

English | 中文

安装

pnpm add @jl-org/optimize-assets-size sharp -D

CLI 用法

npx optimize-assets-size --dirs=src/assets,public [options]

参数

| 参数 | 说明 | 默认值 | |------|------|--------| | --dirs=a,b | 必填，逗号分隔多个根目录（相对 cwd） | - | | --tsconfig=path | 指定 tsconfig 路径读取 paths | 自动查找 tsconfig.json / tsconfig.app.json | | --alias kv | kv 映射覆盖 alias（优先级最高），如 @/=src,hooks=lib | - | | --dry-run | 预览模式，不实际写文件 | false | | --force | 强制覆盖（即使压后更大） | false | | --rewrite-imports | 自动替换源码中的 alias 路径 | false | | --max-width=N | 限制最大宽度（>= 16） | 不限制 | | --formats=a,b | 参与优选的额外输出格式：webp / png / jpg / jpeg / avif（与同格式重压缩一起比体积） | webp,png | | --formats= | 空值：不做跨格式编码，仅同格式重压缩 | - |

示例

# 预览压缩效果
npx optimize-assets-size --dirs=src --dry-run

# 自动优选编码 + 重写 import（扩展名变化时从 tsconfig 读 alias）
npx optimize-assets-size --dirs=src,public \
  --tsconfig=tsconfig.app.json \
  --rewrite-imports

# 手动指定 alias 映射（优先级高于 tsconfig）
npx optimize-assets-size --dirs=src \
  --alias "@/=src,hooks=../hooks/src" \
  --rewrite-imports

# 限制最大宽度为 1920px
npx optimize-assets-size --dirs=src --max-width=1920

# 只在 webp / avif 中选（并与同格式比较）
npx optimize-assets-size --dirs=src --formats=webp,avif

# 只做同格式压缩，不转其它格式
npx optimize-assets-size --dirs=src --formats=

Alias 解析优先级

1. --alias kv 映射 — 最高优先级，直接覆盖
2. --tsconfig 读取 compilerOptions.paths — 未指定时自动查找 tsconfig.json → tsconfig.app.json

API 用法

import {
  chooseBestRasterEncoding,
  collectRasterFiles,
  computeAliasRewrites,
  encodeWebp,
  optimizeSameFormat,
  parseArgs,
  resolveAliasPaths,
  stripJsonComments,
} from 'optimize-assets-size'
import fs from 'node:fs'

// 解析 tsconfig 获取 alias 映射
const aliasPaths = resolveAliasPaths(null, 'tsconfig.app.json')

// 收集所有栅格图文件
const files = await collectRasterFiles(['src/assets'])

const buf = fs.readFileSync('photo.jpg')

// 同格式压缩
const optimized = await optimizeSameFormat(buf, '.jpg', 1920)

// 默认与同格式一起比较 webp + png；传 [] 则仅同格式
const best = await chooseBestRasterEncoding(buf, '.jpg', 1920)
const bestAvif = await chooseBestRasterEncoding(buf, '.jpg', 1920, {
  formatAllowlist: ['webp', 'avif'],
})
const sameOnly = await chooseBestRasterEncoding(buf, '.jpg', 1920, {
  formatAllowlist: [],
})

// 仅转 WebP（程序 API）
const webp = await encodeWebp(buf, 1920)

// 计算 import 路径替换对（目标扩展名以 best.outExt 为准）
const rewrites = computeAliasRewrites(
  '/project/src/assets/logo.png',
  '/project/src/assets/logo.webp',
  aliasPaths,
)

压缩参数

| 格式 | 参数 | |------|------| | JPEG | quality: 82, mozjpeg: true | | PNG | compressionLevel: 9, quality: 85, effort: 10 | | WebP | quality: 82, effort: 4 | | AVIF | quality: 70, effort: 4 |

License

MIT