rv-image-optimize

高性能、跨框架的图片优化与懒加载解决方案。提供 React 组件、通用工具函数、浏览器/Node 压缩、Vite 静态图片打包压缩、上传编排和 IndexedDB 缓存能力，适合 React、Vue、Vite、Webpack、Node 脚本和 CLI 场景。

最新版本：v3.0.11

3.x 只保证 exports 中声明的正式入口兼容，不再支持 src/*、lib/*、dist/* 这类内部文件直引。

在线预览

插件亮点

• 🚀 跨框架可用：同一个包同时覆盖 React 组件、Vue / Webpack / 原生 JS 工具函数，以及 Node / CLI 场景
• 🌐 跨语言调用友好：Java / Python / PHP 等后端可直接通过 CLI 复用压缩能力，不必先单独重写图片处理链路
• 🖼️ 图片优化能力完整：支持多 CDN 参数适配、自动格式选择、响应式图片、懒加载和渐进式加载
• ⚙️ 浏览器与服务端双压缩链路：既支持浏览器端压缩 / 无损压缩，也支持 node-compress 在 Node 环境原生处理图片
• 📦 支持静态图片打包压缩：可通过 rv-image-optimize/vite-plugin 在 build 后自动优化 dist 内静态图片
• 📤 上传链路可复用：提供 upload-core 和 upload 两层入口，既能单独上传，也能做“压缩后上传”编排
• 💾 缓存体系完善：内置 IndexedDB + Worker 缓存能力，支持多库多表、自动过期和配额检测
• 🧩 JS / TS 都可直接接入：从 3.x 开始提供官方 .d.ts，不需要消费者手写模块声明
• 🤖 Agent 集成友好：可直接接入 Cursor、Claude Code、skills 型 Agent，推荐通过 CLI + --json 进行稳定调用

Agent 集成亮点

• 支持 Cursor、Claude Code、skills 型 Agent 直接接入
• 推荐统一通过 rv-image-optimize CLI 调用，避免 Agent 临时拼接脚本
• 支持 --json 结构化输出，方便 Agent 稳定解析成功数、失败数、输出目录和压缩结果
• 既适合“安全输出到新目录”，也支持在用户明确授权时执行删除原图或替换原图
• 详细接入方式、推荐提示词和 skill 规则见 AGENT_INTEGRATION.md

安装

npm install rv-image-optimize

JS / TS 是否开箱即用

• JavaScript：开箱即用
• TypeScript：从 3.x 开始提供官方 .d.ts，开箱即用
• React 项目：使用 rv-image-optimize、rv-image-optimize/LazyImage、rv-image-optimize/ProgressiveImage、rv-image-optimize/styles
• Vue / 原生 JS / Webpack：使用 rv-image-optimize/utils-only
• Vite 项目打包：可额外使用 rv-image-optimize/vite-plugin，在 vite build / npm run build 阶段自动优化 dist 中的静态图片

如果你是第一次安装并直接使用 3.x，按本 README 示例接入即可，不需要看迁移文档。

快速开始

React

import { LazyImage } from 'rv-image-optimize';
import 'rv-image-optimize/styles';

export default function App() {
  return (
    <LazyImage
      src="https://example.com/image.jpg"
      width={800}
      height={600}
      optimize={{ width: 800, quality: 85, autoFormat: true }}
    />
  );
}

Vue / 原生 JS / Webpack

import { optimizeImageUrl, loadImageWithCache } from 'rv-image-optimize/utils-only';

const optimized = optimizeImageUrl('https://example.com/image.jpg', {
  width: 800,
  quality: 80,
  format: 'webp',
});

const blobUrl = await loadImageWithCache(optimized);

如果你是 Webpack 项目，建议继续查看 WEBPACK_USAGE.md。

浏览器端压缩返回值

compressImageInBrowser() 现在返回结构化结果对象，而不是单独的 dataURL 字符串：

import { compressImageInBrowser } from 'rv-image-optimize/utils-only';

const result = await compressImageInBrowser(file, {
  maxWidth: 1280,
  quality: 0.82,
  format: 'webp',
});

console.log(result.compressedSize, result.savedPercentage);
previewImg.src = result.dataURL || result.url;
formData.append('file', result.file);

常用字段：

• file：压缩后的 File，适合直接上传
• blob：压缩后的 Blob
• dataURL / url：可直接用于预览
• originalSize / compressedSize / savedPercentage
• compressedFileName / compressedFormat

Node / CLI

import { compressImageFile } from 'rv-image-optimize/node-compress';

const result = await compressImageFile('./images/demo.png', {
  outputDir: './compressed',
  format: 'webp',
  quality: 82,
});

console.log(result.outputPath, result.compressedSizeFormatted);

rv-image-optimize ./images --output-dir ./compressed --format webp --quality 82

Vite 静态图片打包压缩

适用于 Vite 项目构建阶段。接入后会在 vite build 或 npm run build 产物生成后，自动扫描并优化 dist 里的静态图片文件；默认不影响 vite dev 开发模式，也不改图片引用路径。

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import { rvImageOptimizeVitePlugin } from 'rv-image-optimize/vite-plugin'

export default defineConfig({
  plugins: [
    vue(),
    rvImageOptimizeVitePlugin({
      includeFormats: ['png', 'webp', 'avif', 'svg'],
    }),
  ],
})

默认更适合处理这些静态资源：

• png
• webp
• avif
• svg

如果你需要更完整的配置项和注意事项，请查看 STATIC_IMAGE_BUILD_PLUGIN.md。

Webpack 静态图片打包压缩

适用于 Webpack 4 / 5 项目构建阶段。接入后会直接处理 compilation assets 中的图片资源，保持资源名与引用路径不变，只在体积变小时覆盖构建产物。

import path from 'node:path';
import { rvImageOptimizeWebpackPlugin } from 'rv-image-optimize/webpack-plugin';

export default {
  mode: 'production',
  entry: './src/index.js',
  output: {
    path: path.resolve('dist'),
    filename: 'bundle.js',
  },
  plugins: [
    rvImageOptimizeWebpackPlugin({
      includeFormats: ['png', 'webp', 'avif', 'svg'],
    }),
  ],
};

如果你需要更完整的配置项和差异说明，请查看 WEBPACK_USAGE.md。

正式入口

| 入口 | 说明 | | --- | --- | | rv-image-optimize | React 根入口，导出 LazyImage / ProgressiveImage 与常用能力 | | rv-image-optimize/LazyImage | React LazyImage 单独入口 | | rv-image-optimize/ProgressiveImage | React ProgressiveImage 单独入口 | | rv-image-optimize/styles | React 组件样式 | | rv-image-optimize/utils-only | 不含 React 的工具函数入口，适合 Vue / Webpack / 原生 JS | | rv-image-optimize/cache | 通用缓存能力 | | rv-image-optimize/lossless | 浏览器端无损压缩 | | rv-image-optimize/node-compress | Node 原生压缩 | | rv-image-optimize/vite-plugin | Vite 构建后静态图片压缩插件 | | rv-image-optimize/webpack-plugin | Webpack 4 / 5 构建期静态图片压缩插件 | | rv-image-optimize/upload-core | 无 UI 上传核心 | | rv-image-optimize/upload | 浏览器端压缩后上传编排 |

框架接入建议

• React：优先使用 rv-image-optimize 或 rv-image-optimize/LazyImage
• Vue / Vite：运行时统一使用 rv-image-optimize/utils-only，构建期静态图可配合 rv-image-optimize/vite-plugin
• Webpack 5：运行时可直接使用 rv-image-optimize/utils-only，构建期静态图可配合 rv-image-optimize/webpack-plugin
• Webpack 4：运行时使用 rv-image-optimize/utils-only 并为 .worker.js 配置 worker-loader，构建期静态图可配合 rv-image-optimize/webpack-plugin
• Node / CLI：使用 rv-image-optimize/node-compress 或直接调用 rv-image-optimize CLI
• Agent / Cursor / Claude Code / skills：优先通过 rv-image-optimize CLI 调用，并配合 --json 读取结构化结果

常见问题

| 问题 | 解决方式 | | --- | --- | | Vue 中报 ReactCurrentDispatcher | 导入了 React 入口，改用 rv-image-optimize/utils-only | | Webpack Module parse failed | 补 worker-loader，或检查是否误用了不适合当前环境的入口 | | Webpack 构建期想自动压缩静态图片 | 使用 rv-image-optimize/webpack-plugin | | Node 里调用 losslessCompress 报浏览器 API 错误 | 改用 rv-image-optimize/node-compress | | 想压缩成功后删除或替换原图 | CLI 使用 --delete-original 或 --replace-original | | 想删除整个缓存数据库但浏览器一直挂起 | 当前版本会在删库或版本变更时主动关闭主线程 / Worker 持有的 IndexedDB 连接，并保留阻塞等待与超时保护；如果开发环境里还有旧页面或同源标签页占用，刷新页面或关闭相关标签页后再重试 |

迁移与详细文档

README 只保留首页摘要。以下细节请看对应文档：

| 文档 | 内容 | | --- | --- | | REACT_MIGRATION_3X.md | React 项目从 2.x 升级到 3.x 的迁移对照 | | VUE_USAGE.md | Vue / Vite / Webpack 详细接入说明 | | WEBPACK_USAGE.md | Webpack 5 / Webpack 4 / React / 原生 JS 接入说明 | | ProgressiveImage.md | 渐进式加载配置与示例 | | LOSSLESS_COMPRESS.md | 无损压缩能力与 API | | NODE_CLI_COMPRESS.md | Node API 与 CLI 压缩入口 | | STATIC_IMAGE_BUILD_PLUGIN.md | Vite / Webpack 静态图片打包压缩插件说明 | | MULTI_LANGUAGE_CLI_USAGE.md | Java / Python / PHP 等后端通过 CLI 调用说明 | | AI_TOOLKIT.md | 专门给 AI / Agent 使用的工具摘要与提示词模板 | | AGENTS.md | 仓库级 Agent 规则，适合支持自动读取仓库指引的 AI | | UPLOAD_PIPELINE.md | 上传编排、upload-core / upload 说明 | | STYLE_CUSTOMIZATION.md | 样式自定义 | | AGENT_INTEGRATION.md | Cursor / Claude Code / skills / Agent CLI 集成说明 | | PUBLISH.md | npm 发版流程 | | CHANGELOG.md | 版本变更记录 |

License

ISC