svg2img-cli

批量将 SVG 转为 PNG/JPEG/WebP 的命令行工具，基于 Headless Chrome（Puppeteer）渲染。支持内联外链资源、加载自定义/网络字体、尺寸与质量控制、相对目录结构保持与命名策略。

特性

• 批处理：文件/目录/通配符（glob）均可
• 多格式：PNG / JPEG / WebP（可多选），质量可控
• 尺寸控制：viewBox 自适应，或指定宽/高/缩放倍率
• 资源与字体：内联外链图片/样式，支持本地与网络字体
• 输出结构：保持相对结构或扁平输出，命名模板
• 进度与稳定：串行渲染、超时控制、失败重试一次
• 跨平台：Windows / macOS / Linux

环境要求

• Node.js ≥ 18
• 首次安装 Puppeteer 会自动下载 Chromium（体积较大）

安装

npm i -g svg2img-cli
# 或在项目内安装
npm i -D svg2img-cli

快速开始

# 最小示例
svg2img -i examples/sample.svg -o out

# 多格式导出 + 质量/背景
svg2img -i "examples/**/*.svg" -o out -f png jpeg webp --quality 85 --background white

# 指定尺寸（只给一边则等比推算）
svg2img -i icons/*.svg -o out --width 800

# 保持相对结构（基于 --root）
svg2img -i "assets/**/*.svg" -o out --root assets

# 扁平输出 + 命名模板
svg2img -i assets -o out --flat --name-template "icon-{name}"

# 跳过已存在文件或覆盖
svg2img -i assets -o out --skip-existing
svg2img -i assets -o out --overwrite

CLI 用法

svg2img --help

主要选项：

• -i, --input <patterns...> 输入 SVG 路径或 glob；省略时默认扫描 **/*.svg
• -o, --out-dir 输出目录（默认 dist）
• -f, --format <fmt...> 输出格式：png | jpeg | webp（可多选；别名：jpg=jpeg）
• --width / --height 目标尺寸（像素），只填一边将按原始宽高比推算
• --scale 缩放倍率（如 2 表示 2x）
• --background 背景色，默认透明；JPEG 不支持透明，未指定则使用白色
• --quality <0-100> JPEG/WebP 质量（默认 92）
• --timeout 单文件超时时间（默认 30000）
• --font <pathsOrUrls...> 自定义字体（本地路径或 URL），支持 Family=src 语法
• --overwrite 覆盖已存在的输出文件
• --skip-existing 已存在则跳过（不报错）
• --ignore <glob...> 忽略的 glob 模式（如 /node_modules/）
• --root 保持相对结构的根目录（默认当前工作目录）
• --flat 不保留目录层级，全部输出到 out-dir
• --name-template 命名模板（默认 {name}），支持占位符 {name}
• --no-progress 关闭进度动画
• --silent 静默模式，仅输出错误

字体与资源

• 字体：支持 Family=src 或直接传 src。未指定 Family 时用文件名（不含扩展名）作为字体族名

  svg2img -i a.svg -o out --font "MyFont=./fonts/Inter-Variable.woff2"

• 外链资源与样式将自动内联（link rel=stylesheet、style 内的 @import 与 url(...)、image/use/feImage 的 href）

进阶

• 超时与重试：每个文件默认超时 30s，失败会自动重试 1 次
• 透明度：PNG/WebP 支持透明；JPEG 不支持透明，将使用背景色（默认白色）
• 目录结构：结合 --root/--flat/--name-template 构建输出路径

故障排查

• Puppeteer 安装慢/失败：检查网络代理或配置 PUPPETEER_DOWNLOAD_BASE 镜像
• 字体不生效：确保传入的字体族名与 SVG/CSS 中使用一致，或在 SVG 中引用该字体族名
• 外链资源：确保可访问，或提前替换为 file:///data: URI

开发与调试

# 构建
npm run build

# 样例演示（覆盖输出）
npm run demo

许可证

MIT