optimize-images

Web 项目的图像优化

使用现代工具优化图像，提升 Web 性能。此技能提供了压缩 PNG 和 JPEG 图像的脚本与工作流，同时保持视觉质量。

何时使用此技能

• 为生产环境的 Web 部署准备图像
• 缩短页面加载时间
• 优化 public/images 目录
• 批量压缩屏幕截图、水彩画和照片
• 审核优化前后的图像大小

核心工具：Sharp

Sharp 是基于 libvips 构建的最快 Node.js 图像处理库。将其用于所有图像优化任务。

安装 Sharp

bun add -d sharp
# or
npm install -D sharp

快速入门工作流

1. 对当前状态进行基准测试

优化前，测量基准指标：

# Total size and count
du -sh public/images/
find public/images -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" \) | wc -l

# Size by format
find public/images -name "*.png" -exec du -ch {} + | tail -1
find public/images \( -name "*.jpg" -o -name "*.jpeg" \) -exec du -ch {} + | tail -1

# Top 20 largest files
find public/images -type f \( -name "*.png" -o -name "*.jpg" \) -exec ls -la {} \; | \
  awk '{print $5, $9}' | sort -rn | head -20 | \
  awk '{printf "%6.1fMB  %s\n", $1/1048576, $2}'

2. 在单张图像上测试

务必先在一张图像上测试优化设置：

bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --file=public/images/largest-image.png --dry-run

3. 执行完整优化

确认设置效果良好后：

bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts

4. 验证结果

# Compare before/after
du -sh public/images/

# Visually inspect optimized images
# Run production build
bun run build

优化设置

PNG 优化

使用 Sharp 的 PNG 编码器并启用调色板模式，以实现最大压缩率：

sharp(filePath)
  .png({
    quality: 80,           // 1-100, lower = smaller
    compressionLevel: 9,   // 0-9, higher = more compression
    adaptiveFiltering: true,
    palette: true,         // Use palette for smaller files
  })
  .toBuffer();

推荐设置：

• 屏幕截图：质量 80，压缩 9
• 照片：质量 85，压缩 9
• 图标/徽标：质量 90，压缩 9（保持清晰锐利）

JPEG 优化

使用 Sharp 和 mozjpeg 实现更出色的压缩：

sharp(filePath)
  .jpeg({
    quality: 80,    // 1-100, lower = smaller
    mozjpeg: true,  // Use mozjpeg encoder
  })
  .toBuffer();

推荐设置：

• 照片：质量 75-80
• 屏幕截图：质量 80-85
• 主视觉图像：质量 85

优化脚本

将 scripts/optimize-images.ts 复制到项目的脚本目录。该脚本会：

1. 递归查找所有 PNG/JPEG 图像
2. 应用压缩设置
3. 覆盖原文件（仅在文件变小时）
4. 报告每个文件节省的空间
5. 显示节省空间的汇总信息

脚本用法

# Dry run (see what would happen)
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --dry-run

# Test single file
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --file=path/to/image.png

# Full optimization
bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts

预期节省空间

未优化的 Web 图像通常可达到以下效果：

图像类型	典型节省比例
屏幕截图（PNG）	40-60%
照片（JPEG）	20-40%
水彩画（PNG）	30-50%
图标（PNG）	10-30%

Next.js 注意事项

Next.js 可通过 next/image 自动优化图像。不过，优化源图像仍有帮助：

1. 更快的构建 - 源图像越小，处理速度越快
2. 回退支持 - 非 Next.js 导入也能受益
3. 减少存储空间 - 仓库体积更小
4. 提高 CDN 效率 - 需要缓存/提供的数据更少

即使使用 next/image，也要保持源图像经过优化。

工作流集成

提交前钩子（可选）

添加到 .husky/pre-commit 或 git 钩子中：

# Warn if large images are being committed
find public/images -name "*.png" -size +500k -exec echo "Warning: Large image: {}" \;

CI/CD 检查

添加到构建流水线中：

# Fail if images exceed threshold
MAX_SIZE=79  # MB
CURRENT=$(du -sm public/images | cut -f1)
if [ "$CURRENT" -gt "$MAX_SIZE" ]; then
  echo "Error: Images exceed ${MAX_SIZE}MB (currently ${CURRENT}MB)"
  exit 1
fi

故障排除

图像质量太低

提高质量设置：

• PNG：将 quality 提高到 85-90
• JPEG：将 quality 提高到 85-90

透明 PNG 显示异常

确保 palette: true 能正确处理透明度。对于复杂的透明效果，请使用：

.png({ quality: 85, palette: false })

Sharp 安装问题

在 macOS 上，确保 libvips 可用：

brew install vips

或者让 sharp 下载预编译二进制文件：

npm rebuild sharp

其他资源

参考文件

• references/optimization-guide.md - 压缩算法与格式对比详解
• references/sharp-api.md - 完整的 sharp 图像 API 参考

脚本

• scripts/optimize-images.ts - 可用于生产环境的优化脚本

上下文纪律

**不要将优化后的图像重新读入上下文。**脚本会输出汇总表，其中包含文件大小、节省比例和总计。如果需要验证质量，请让用户目视检查结果。即使经过优化，处理大量文件时，图像也可能足够大，导致上下文窗口被占满。

总结

1. 安装 sharp：bun add -d sharp
2. 将优化脚本复制到项目
3. 基准测试：du -sh public/images/
4. 测试：bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts --dry-run
5. 优化：bun run --cwd ${CLAUDE_PLUGIN_ROOT} ${CLAUDE_PLUGIN_ROOT}/skills/optimize-images/scripts/optimize-images.ts
6. 验证：检查大小和视觉质量
7. 提交：将优化后的图片纳入部署