nuxt-tinify-img

Nuxt 模块：构建时使用 Tinify（TinyPNG）API 对图片进行压缩。

在 build:before 钩子中扫描指定目录下的图片，调用 TinyPNG API 就地压缩，并通过本地缓存文件跳过已压缩的图片，避免重复消耗每月免费压缩额度。

安装

本包为独立 npm 包，直接通过包管理器安装即可：

pnpm add nuxt-tinify-img
# 或
npm install nuxt-tinify-img

快速开始

在 nuxt.config.ts 中注册模块并配置：

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-tinify-img'],

  tinifyImg: {
    // 建议从环境变量读取，未配置时模块 graceful 跳过压缩（不报错）
    apiKey: process.env.TINIFY_API_KEY || '',
    dirs: ['app/assets/img'],
  },
})

环境变量示例（.env.prod）：

TINIFY_API_KEY=xxxxxxxx

模块顺序：modules: ['nuxt-tinify-img', 'nuxt-alioss-upload'] —— 先压缩后上传。

配置项

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | apiKey | string | 必填 | Tinify API Key，缺失时跳过压缩并打印警告 | | dirs | string[] | ['app/assets/img'] | 要扫描的目录（相对项目根目录） | | extensions | string[] | ['.png', '.jpg', '.jpeg', '.webp'] | 处理的图片扩展名 | | cacheFile | string | '.tinify-cache.json' | 缓存文件名（相对项目根目录） | | silent | boolean | false | 为 true 时关闭日志输出 |

工作原理

1. 触发时机：build:before 钩子，仅在非 dev 模式且配置了 apiKey 时执行。
2. 扫描文件：用 fast-glob 按 dirs + extensions 组合模式扫描图片。
3. 缓存判断：缓存文件（默认 .tinify-cache.json）记录 项目相对路径 → MD5 hash（相对路径使缓存可在 CI/测试环境等不同机器间复用）。若某文件的当前 hash 与缓存一致，则跳过（说明自上次压缩后未变更）。旧版本生成的绝对路径缓存会在加载时自动迁移为相对路径。
4. 就地压缩：
   • 将原文件重命名为 .tinify-backup 临时文件。
   • 调用 tinify.fromFile(backup).toFile(原路径)，将压缩结果写回原路径。
   • 若压缩结果不小于原文件（未变小），恢复原始文件，仅缓存不计数（避免白费压缩额度）。
   • 压缩成功且更小则删除备份，并更新缓存。
5. 失败兜底：单文件失败（如文件在扫描与处理之间消失）不会中断整个 build:before；出错时尽力恢复备份文件。

回答常见疑问：压缩是就地替换原文件的，压缩成功后原路径就是压缩后的图片。原始文件通过临时 .tinify-backup 中转，成功即删除；失败或未变小则恢复。

日志输出

[nuxt-tinify-img] Cache file: /path/to/.tinify-cache.json
[nuxt-tinify-img] Cache entries loaded: 12
[nuxt-tinify-img] Found 34 image files
[nuxt-tinify-img] Compressing: app/assets/img/pc/home/banner.png
[nuxt-tinify-img]   ✅ app/assets/img/pc/home/banner.png: 512.0KB → 218.0KB (57.4%)
[nuxt-tinify-img] ────────────────────────────────────
[nuxt-tinify-img] Done: 30 compressed, 3 skipped, 1 failed
[nuxt-tinify-img] Total saved: 8120.5KB
[nuxt-tinify-img] Monthly compressions used: 45

Monthly compressions used 来自 Tinify 返回的本月已用压缩次数（该字段在首次 API 调用后可用）。

注意事项

• 不要直接修改 .tinify-cache.json，它由模块自动维护。
• 若手动替换或改动了图片，其 MD5 会变化，模块会自动重新压缩。
• 未配置 TINIFY_API_KEY 时模块打印警告并跳过，不会导致构建失败。
• 压缩额度为 TinyPNG 每月免费 500 次，缓存机制正是为了控制额度消耗。

相关

• nuxt-alioss-upload — 构建后将静态资源上传到阿里云 OSS（与 nuxt-tinify-img 配合：先压缩后上传）。
• TinyPNG API 文档：https://tinypng.com/developers