Baoyu Compress Image

核心用法

baoyu-compress-image 是一款跨平台图片压缩技能，通过 TypeScript/Bun 运行时驱动，内置四层工具链自动降级策略：优先调用 macOS 原生 sips，其次 cwebp 官方工具，再 fallback 至 ImageMagick，最终使用 Sharp Node.js 库兜底。用户仅需指定输入路径，即可一键完成单文件或整目录递归压缩。

CLI 设计简洁直观：

bun /path/to/scripts/main.ts <input> [options]

关键参数包括格式指定（-f webp|png|jpeg）、质量调节（-q 0-100，默认 80）、保留原文件（-k）、递归子目录（-r）及结构化 JSON 输出（--json）。输出路径默认与原文件同目录，仅扩展名变更。

显著优点

1. 零配置开箱即用：智能探测系统已安装工具，无需手动安装依赖链
2. 多层级容错机制：四层工具链确保在 macOS/Linux/Windows 均有可行方案
3. 现代格式优先：默认输出 WebP，兼顾压缩率与浏览器兼容性
4. 工程化友好：支持项目级、用户级、XDG 配置三级 EXTEND.md 覆盖，便于团队统一规范

潜在局限

• 运行时依赖：需预装 Bun 或允许通过 npx 动态获取，纯净环境中仍需首次准备
• 无 GUI 交互：纯 CLI 工具，对非技术用户存在学习成本
• 格式支持边界：输入格式受限于底层工具链（如 sips 不支持某些 RAW 变体）
• 无在线压缩：纯本地处理，无法利用云端算力处理超大文件

适合人群

• 前端开发者：构建流程中自动化图片优化
• 运维/DevOps：批量处理服务器静态资源
• 内容创作者：本地快速压缩素材上传至平台
• CI/CD 流水线：轻量级容器内集成

常规风险

| 场景 | 说明 |

|------|------|

| 质量过度压缩 | 低于 60 的 quality 可能导致视觉劣化，建议预览确认 |

| 源文件覆盖 | 默认 `-k false` 会直接替换，重要素材建议显式启用 `--keep` |

| 递归误操作 | `-r` 处理大目录时可能耗时显著，建议先 `--json`  dry-run 评估 |

| 工具链缺失 | 若四层工具均未安装，脚本将报错退出，需前置依赖检查 |

整体而言，该技能以"约定优于配置"为设计理念，是本地图片资源优化的实用利器。

核心用法

baoyu-compress-image 是一款本地图像压缩 CLI 工具，专为需要高效优化图片体积的用户设计。用户通过简单的命令行指令即可将 PNG、JPEG 等格式的图像转换为 WebP（默认）、PNG 或 JPEG 格式，并支持质量调节（0-100，默认 80）、递归目录处理、保留原文件等选项。

工具采用多引擎智能降级策略：优先使用 macOS 原生 sips，其次 Google cwebp，再到 ImageMagick convert，最后 fallback 到 Node.js sharp 库，确保在不同环境下都能获得最佳压缩效果。运行依赖 bun 或 npx，支持通过 EXTEND.md 进行项目级、用户级配置覆盖。

显著优点

1. 智能引擎调度：自动检测系统可用工具，优先使用原生/系统级工具获得最佳性能，无需用户手动配置。
2. 零网络依赖：纯本地处理，不上传图片至云端，保护用户隐私数据安全。
3. 灵活配置体系：支持三级配置覆盖（项目目录 → XDG 配置目录 → 用户主目录），满足不同场景需求。
4. 输出友好：提供人类可读的文件大小对比（如"245KB → 89KB, 64% reduction"）及 JSON 格式输出，便于集成到 CI/CD 流程。
5. 轻量高效：代码仅 421 行，依赖成熟可靠的 sharp 库，无冗余功能。

潜在缺点与局限性

1. 环境依赖较重：必须预装 bun 或 npx 才能运行，Windows 用户需额外配置。
2. 外部命令调用：依赖 sips（macOS 专属）、cwebp、convert 等系统工具，若均未安装则性能下降为纯 sharp 处理。
3. 无图像预览功能：压缩前无法可视化对比效果，需反复调整质量参数。
4. 格式支持有限：仅支持 WebP/PNG/JPEG 三种输出格式，不支持 AVIF、HEIC 等新兴格式。
5. T3 来源信任度：来自个人开发者（GitHub: JimLiu），非组织背书，虽代码开源可审计，但长期维护稳定性存疑。

适合的目标群体

• 前端开发者：需要为 Web 项目批量优化图片资源，减少加载时间。
• 运营/内容创作者：处理大量社交媒体图片，控制平台上传大小限制。
• DevOps 工程师：集成到构建脚本或 Git 钩子，自动化资源优化流程。
• 注重隐私的用户：拒绝云端压缩服务，坚持本地处理的保守型用户。

使用风险

1. 命令注入风险（低）：虽对输入路径有基础验证，但极端情况下特殊字符可能引发意外行为，建议避免处理不可信来源的文件名。
2. 临时文件残留：压缩过程创建 .tmp 临时文件，异常中断时可能残留，需手动清理或等待后续增强的容错机制。
3. 大文件资源耗尽：无内置文件大小限制，处理超大图像（如数百 MB 的 TIFF/RAW）可能导致内存或磁盘空间不足。
4. 引擎行为差异：不同压缩引擎（sips vs cwebp vs sharp）的输出质量和文件大小存在细微差别，跨环境结果可能不一致。