更新记录

1.0.0（2026-07-19）

首个公开版本。

  • 路径兼容：支持 file:// URI 直传（uni.chooseImage 的 tempFilePath 原样可用，内置规范化）； _doc/ 等约定相对路径请先转绝对路径（后续版本桥接层内置转换）。

  • 验证：自研核心 162 项单测全绿；Android 已用云打包自定义基座在模拟器端到端实测 （压缩/灰度/模糊/旋转/裁剪/转码六项代表性 API 逐个点验，输出格式与尺寸语义核验通过）。

  • 53 个 JS API（49 个原生 + 4 个 AI 网络层）：

    • 压缩：等比 / 微信式 / 缩略图 / 定体积（二分质量）/ 批量并行（多线程）/ 智能选格式
    • 水印：文字（内置字体 + 自定义 ttf）/ 图片 logo 九宫格 / 平铺防盗 / 抗压缩盲水印（文本 + logo 嵌入、抗缩放提取、批量溯源、鲁棒性自检）
    • 修图：灰度 / 高斯模糊 / 亮度对比度 / 怀旧 / 暗角 / 锐化 / 饱和度 / 一键美颜（磨皮美白）/ 自动增强
    • 几何：旋转 / 翻转 / 裁剪 / 精确缩放 / 规格化（contain/cover/stretch）/ 圆角 / 描边
    • 隐私与合规：EXIF 读取（含 GPS 十进制）/ 元数据擦除 / 马赛克打码
    • 拼图：多图长图拼接 /

平台兼容性

uni-app x(5.14)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × 5.0 12 × ×

nex-image —— 高性能图像处理

自研高性能原生图像处理核心（解码 / 缩放 / 滤镜 / 几何 / 格式转换），提供 uni-app 可调的 JS API。 仅支持 App 端（Android / iOS），H5 / 小程序加载不了原生库。

同一份 utssdk 插件同时支持 uni-app x（uvue） 与 经典 uni-app（vue3），无需分叉。 全部 路径进 / 路径出：传 src / dest 文件路径，原生层读文件 → 处理 → 写文件 → 返回结果，避免大图 buffer 进 JS 层。

API

JS API 签名 说明
imageInfo imageInfo(path): ImageInfo 探测宽高 / 源格式名 / 文件字节数
compressImage compressImage(src, dest, maxWidth, maxHeight, quality, format): OpResult 等比缩小到 ≤ maxWidth×maxHeight（不放大；维度传 0 表示不限该维）
compressLikeWechat compressLikeWechat(src, dest, quality, format): OpResult 微信式压缩：短边 > 1280 则等比缩到短边 1280（长图/小图不缩放），按 format 编码
thumbnail thumbnail(src, dest, size, quality): OpResult 最长边 ≤ size 的缩略图，jpeg 输出
grayscale grayscale(src, dest): OpResult 灰度化
gaussianBlur gaussianBlur(src, dest, sigma): OpResult 高斯模糊（sigma 为标准差）
adjust adjust(src, dest, brightness, contrast): OpResult 亮度（-255..=255）/ 对比度（倍率，1.0 不变）
rotate rotate(src, dest, degrees): OpResult 旋转，仅 90 / 180 / 270，其余抛错
flip flip(src, dest, horizontal): OpResult 翻转，horizontal true 水平 / false 垂直
crop crop(src, dest, x, y, width, height): OpResult 裁剪，越界抛错
resizeExact resizeExact(src, dest, width, height): OpResult 精确缩放到 width×height（不保比例）
convertFormat convertFormat(src, dest, format, quality): OpResult 格式转换（按 format 重新编码）

上架前处理一条龙：

JS API 签名 说明
compressToTargetSize compressToTargetSize(src, dest, maxBytes, format): CompressResult 压到指定体积（≤ maxBytes 字节）：jpeg/webp 二分质量、png 降尺寸；达不到则 best-effort 并标 reachedTarget=false
compressBatch compressBatch(srcs, destDir, maxWidth, maxHeight, quality, format): BatchItemResult[] 批量压缩到目录，单图失败隔离不中断整批
smartCompress smartCompress(src, dest, quality?): CompressResult 智能压缩：按内容自动选格式（透明→webp、照片→jpeg、少色→png）与默认质量
normalizeSize normalizeSize(src, dest, width, height, fit, bgColor): OpResult 规格化到精确尺寸：fit = contain(留白) / cover(裁切) / stretch
imageWatermark imageWatermark(src, dest, watermarkPath, position, opacity, scale): OpResult 图片/logo 水印，九宫格定位 + 透明度 + 相对缩放
roundCorners roundCorners(src, dest, radius): OpResult 圆角（输出 PNG 保留透明）
addBorder addBorder(src, dest, width, color): OpResult 描边 / 外框（width 像素 color 边）

position 取九宫格字符串：'topLeft'|'top'|'topRight'|'left'|'center'|'right'|'bottomLeft'|'bottom'|'bottomRight'；color/bgColor 为 '#RRGGBB' 或 '#RRGGBBAA'。

水印 · 隐私 · 证件照：

JS API 签名 说明
textWatermark textWatermark(src, dest, text, position, fontSize, color, opacity, fontPath): OpResult 文字水印；fontPath 空串 = 内置 Noto Sans（拉丁/数字开箱即用），传 ttf 支持中文/自定义字体
tileWatermark tileWatermark(src, dest, text, fontSize, color, opacity, angle, gap, fontPath): OpResult 平铺/对角重复文字水印（防盗主打）；angle 角度、gap 间隔像素
readExif readExif(src): ExifInfo 读 EXIF：拍摄时间/设备/方向/GPS(十进制)/曝光/ISO/焦距
stripMetadata stripMetadata(src, dest): OpResult 擦除 EXIF/GPS/ICC（隐私 + 瘦身）
idPhoto idPhoto(src, dest, spec, bgColor): OpResult 证件照规格（1inch/2inch/small1inch/small2inch）裁切；bgColor 非空且纯色底输入时换底（不做 AI 抠图），空串 = 仅裁规格

高级 · 隐私 · 防盗：

JS API 签名 说明
mosaic mosaic(src, dest, x, y, width, height, blockSize): OpResult 矩形区域马赛克打码（人脸/车牌/证件号隐私），blockSize 控格子大小
concatImages concatImages(srcs, dest, direction, gap, bgColor): OpResult 多图长图拼接：direction = vertical/horizontal，居中对齐 + gap 间隔 + bgColor 填充
collage collage(srcs, dest, cols, cellSize, gap, bgColor): OpResult 网格拼图：cols 列网格，每格 cellSize 方形 cover 填充（朋友圈/海报拼图）
splitGrid splitGrid(src, destDir, rows, cols, prefix): number 等分切图（九宫格），rows×cols 块写 destDir，返回块数（发布切图）
blindWatermarkEmbed blindWatermarkEmbed(src, dest, text, strength): OpResult 抗压缩盲水印：肉眼不可见地嵌入版权文本，经 JPEG 重压仍可提取（防盗维权）
blindWatermarkExtract blindWatermarkExtract(src, maxLen): string 从含盲水印的图提取文本（无水印 → 空串）；无需 strength 参数
blindWatermarkImageEmbed blindWatermarkImageEmbed(src, dest, logoPath, logoSize, strength): OpResult 盲水印嵌 logo 图：把 logo 缩 logoSize×logoSize 灰度二值化后嵌入（与文本盲水印同引擎、自校验头），嵌自家图标比文本更直观难否认
blindWatermarkImageExtract blindWatermarkImageExtract(src, dest): OpResult 从含 logo 盲水印的图重建 logoSize×logoSize 黑白 logo 写 dest（无需原图/strength；无水印 → 抛错）
blindWatermarkExtractRobust blindWatermarkExtractRobust(src, maxLen, hintWidth, hintHeight): BlindExtractResult 抗缩放提取：先按原样提取，失败则按 hintWidth/hintHeight（可传 0）与内置候选比例盲扫缩放信道（magic 校验防误报），返回命中比例与耗时
blindWatermarkExtractBatch blindWatermarkExtractBatch(srcs, maxLen): BlindBatchItem[] 批量溯源：多图并行提取盲水印（内置有界并行线程池），单图失败隔离不中断整批
blindWatermarkProbe blindWatermarkProbe(src, text, strength): BlindProbeReport 鲁棒性自检：对指定图/文本/强度在内存模拟 JPEG 重压与缩放信道，报告可存活的最低 JPEG 质量、缩放范围与推荐 strength（发布前自测用）

盲水印鲁棒性（实测，不夸大）：无损链路精确还原（含中文）；嵌入后 PSNR 44–46dB（肉眼近似）。抗 JPEG 重压：默认 strength=16 → 质量 q≥85（微信级转发）可恢复；strength=24~32 → q≥75（更激进压缩，代价是水印更可见）；q≤60 不保证。几何攻击：等比缩放可用 blindWatermarkExtractRobust 盲扫候选比例对抗；裁剪/旋转仍不抗（破坏块对齐）。

基础修图滤镜：

JS API 签名 说明
sepia sepia(src, dest): OpResult 怀旧棕调（标准 sepia 颜色矩阵，输出恒 R≥G≥B 暖棕）
vignette vignette(src, dest, strength): OpResult 暗角：中心→四角径向压暗，strength∈[0,1]（越大四角越暗，自动钳制）
sharpen sharpen(src, dest, amount): OpResult 锐化（USM 非锐化掩模），amount 控强度（须为正有限数）
saturation saturation(src, dest, factor): OpResult 饱和度：factor=1 不变、0=灰度、>1 增艳

strength 自动钳到 [0,1]、非有限抛错；amount 须 >0 且有限、否则抛错；factor 须 ≥0 且有限、否则抛错。

一键美颜 · 自动增强：

JS API 签名 说明
beautify beautify(src, dest, smooth, whiten): OpResult 一键美颜：双边滤波磨皮（保边平滑，平坦区变光滑、边缘保留），smooth∈[0,1] 控强度（0 仅美白）+ 向白提亮 whiten∈[0,1]（0 不变）
autoEnhance autoEnhance(src, dest): OpResult 一键自动增强：灰世界白平衡（纠偏色）+ 自动对比度（直方图拉伸）+ 轻微饱和度提升

smooth/whiten 自动钳到 [0,1]、非有限抛错；smooth 越大磨皮越强（双边滤波半径/σ 越大），smooth=0 近原图只美白。

图片分析 · 查重：

JS API 签名 说明
dominantColors dominantColors(src, count): string[] 主色提取：聚类返回 count 个 #RRGGBB 主色（按占比降序），用于配色/主题色；count=0 抛错
perceptualHash perceptualHash(src): string 感知哈希：返回 16 位十六进制（64 bit），用于相似图/重复图检测
imageDiff imageDiff(srcA, srcB): number 图片差异度：两图感知哈希汉明距离/64 ∈ [0,1]，0=极相似、越大越不同（查重/找改动）

感知哈希定位「结构」而非「颜色」，对整体亮度变化近似稳定——纯色/平坦图区分度低（任意纯色图哈希恒定）。dominantColors 实际返回个数 ≤ count（簇数受采样像素数封顶）。

文档扫描：

JS API 签名 说明
perspectiveCorrect perspectiveCorrect(src, dest, x0,y0,x1,y1,x2,y2,x3,y3, outWidth, outHeight): OpResult 透视校正：给 4 个源角点（左上 TL→右上 TR→右下 BR→左下 BL）求单应变换，把歪斜四边形矫正为 outWidth×outHeight 正视矩形（双线性采样），拉正拍歪的合同/票据/笔记
scanEnhance scanEnhance(src, dest, mode): OpResult 扫描增强：去阴影（除以大模糊背景估计）+ 按 mode 输出——bw（自适应阈值二值，干净黑白扫描件）/ gray（灰度增强）/ color（彩色去阴影）

perspectiveCorrect：outWidth/outHeight=0 或超尺寸上限、角点非有限、退化四边形（4 点共线/零面积）→ 抛错。scanEnhance：未知 mode（仅 bw/gray/color）→ 抛错；bw/gray 输出灰度图。角点检测需调用方自备（MVP 让用户拖 4 角，不含自动找边）。

GIF 合成 / 信息 / 压缩：

JS API 签名 说明
imagesToGif imagesToGif(srcs, dest, delayMs, repeat): OpResult 多图合成动画 GIF：各图作一帧，每帧间隔 delayMs、repeat 控无限循环（表情包 / 短动画刚需）；帧尺寸取各图最大宽高（小帧叠到透明画布原点、不拉伸）
gifInfo gifInfo(src): GifInfo 读 GIF 信息：逻辑屏宽 / 高 / 帧数 / 总时长（毫秒）
compressGif compressGif(src, dest, scale, maxColors): OpResult GIF 瘦身：所有帧按 scale 缩放 + 量化到 ≤ maxColors 色重编码

imagesToGif：空数组 / 帧尺寸为 0 / 超尺寸上限 → 抛错；某图解码失败整体抛错（非隔离）。gifInfo：非 GIF / 坏文件 → 抛错。compressGif：scale 非有限或 ≤0 / maxColors=0 → 抛错；非 GIF → 抛错；maxColors 钳到 [2,256]。GIF 炸弹守卫：解码外部 GIF 时逻辑屏尺寸超上限、帧数超 2000 → 抛错（逐帧流式处理、不整体载入），绝不崩溃。

AI 图像处理（用户自配 AI 服务）：

JS API 签名 说明
aiImageEdit aiImageEdit(src, dest, config): Promise<AiResult> 通用：把图发到你配置的 AI 服务、结果存 dest
aiRemoveBackground aiRemoveBackground(src, dest, config): Promise<AiResult> AI 抠图（= aiImageEdit + 你的抠图服务）
aiSuperResolution aiSuperResolution(src, dest, config): Promise<AiResult> AI 超分放大（= + 你的超分服务）
aiDenoise aiDenoise(src, dest, config): Promise<AiResult> AI 去噪（= + 你的去噪服务）

⚠️ 这 4 个走 UTS 网络层（uni.uploadFile，不调本插件原生核心）：买家填自己的 AiImageConfig（apiUrl/apiKey/model + sendMode/imageField/responseType/resultField），零模型负担、用自己额度、可接任意兼容服务。请求默认 multipart 上传、响应支持 base64Json/urlJson。真实网络/JSON 解析行为与你的服务响应结构相关，建议先用 demo 工程按自己的 uni-app x 版本与服务核对再上生产。

类型

// 输出格式（compressImage / convertFormat 的 format 入参）：字符串 'jpeg' | 'png' | 'webp'
// （'jpg' 视同 'jpeg'；非法值抛错）
type OutFormat = 'jpeg' | 'png' | 'webp';

// imageInfo 返回
type ImageInfo = { width: number; height: number; format: string; sizeBytes: number };

// gifInfo 返回
type GifInfo = { width: number; height: number; frameCount: number; durationMs: number };

// AI 图像处理（add-ai-image）：用户自配 AI 服务的配置 + 结果
type AiImageConfig = { apiUrl: string; apiKey: string; model: string; sendMode: string; imageField: string; responseType: string; resultField: string };
type AiResult = { ok: boolean; dest: string; error: string };

// 其余 API 返回
type OpResult = { width: number; height: number; sizeBytes: number; costMs: number };

// 体积 / 智能压缩返回（compressToTargetSize / smartCompress）
// quality：最终采用质量（PNG 无损取 100）；reachedTarget：是否压到 ≤ maxBytes（smartCompress 恒 true）
type CompressResult = { width: number; height: number; sizeBytes: number; costMs: number; format: string; quality: number; reachedTarget: boolean };

// 批量压缩逐文件结果（compressBatch 返回数组元素）；单项失败时 ok=false、error 有值、outPath/sizeBytes 为空
type BatchItemResult = { srcPath: string; ok: boolean; outPath?: string; sizeBytes?: number; error?: string };

// readExif 返回；除 hasExif 外字段按读到与否可选（GPS 已换算为十进制度，南纬/西经为负）
type ExifInfo = { hasExif: boolean; dateTime?: string; make?: string; model?: string; orientation?: number; gpsLatitude?: number; gpsLongitude?: number; exposureTime?: string; isoSpeed?: number; focalLength?: string };

// 盲水印进阶（blindWatermarkExtractRobust / blindWatermarkExtractBatch / blindWatermarkProbe 返回）
type BlindExtractResult = { text: string; scaleApplied: number; costMs: number };
type BlindBatchItem = { path: string; found: boolean; text: string; scaleApplied: number; costMs: number };
type BlindProbeReport = { minJpegQuality: number; minScale: number; maxScale: number; recommendedStrength: number; costMs: number };
  • 输出格式 format：传字符串 'jpeg' | 'png' | 'webp'（'jpg' 视同 'jpeg'），桥接层映射到原生编码器；其它值抛错。
  • 入参里的尺寸 / 坐标 / 质量等均以 number 传入，桥接层做范围与类型安全转换（如尺寸须为非负整数且不超过 4294967295）；越界或类型不符时抛错。
  • quality：桥接层按物理边界校验，接受 0..=255 的整数（越界或非整数抛错）。其中 Jpeg / Webp 有损编码实际生效范围为 1..=100，落在此区间外的值由编码器自动 clamp（如 0→1、150→100）；Png 无损编码 quality 不参与，传任意合法值均可。建议按业务直接传 1..=100。
  • OpResult.costMs 只计「解码后 → 编码前」处理段，不含磁盘 IO。
  • 编码说明：Jpeg 走渐进式扫描 + 优化霍夫曼编码的高压缩比编码器（按 quality 有损，相同质量下体积更优）；Webp 有损编码（按 quality，体积远小于无损 webp）；Png 无损（quality 不参与）。

用法

import {
  imageInfo,
  compressImage,
  compressLikeWechat,
  thumbnail,
  grayscale,
  gaussianBlur,
  adjust,
  rotate,
  flip,
  crop,
  resizeExact,
  convertFormat,
  sepia,
  vignette,
  sharpen,
  saturation,
  beautify,
  autoEnhance,
  perspectiveCorrect,
  scanEnhance
} from "@/uni_modules/nex-image";

// 探测
const info = imageInfo(srcPath); // { width, height, format, sizeBytes }

// 等比压缩到 ≤ 1280×1280，jpeg 质量 80
const r = compressImage(srcPath, destPath, 1280, 1280, 80, 'jpeg');
console.log(r.width, r.height, r.sizeBytes, r.costMs);

// 微信式压缩：短边 > 1280 缩到短边 1280（长图/小图不缩），jpeg 质量 80
const w = compressLikeWechat(srcPath, destPath, 80, 'jpeg');

// 缩略图：最长边 200
thumbnail(srcPath, destPath, 200, 75);

// 滤镜
grayscale(srcPath, destPath);
gaussianBlur(srcPath, destPath, 2.0);
adjust(srcPath, destPath, 20, 1.2); // 提亮 + 增对比

// 基础修图滤镜
sepia(srcPath, destPath);              // 怀旧棕调
vignette(srcPath, destPath, 0.8);      // 暗角，strength∈[0,1]
sharpen(srcPath, destPath, 1.5);       // 锐化，amount>0
saturation(srcPath, destPath, 0);      // 0=灰度、1=不变、2=增艳

// 一键美颜 / 自动增强
beautify(srcPath, destPath, 0.8, 0.3); // 磨皮 0.8（保边）+ 美白 0.3
autoEnhance(srcPath, destPath);        // 白平衡 + 自动对比度 + 轻微增艳

// 几何
rotate(srcPath, destPath, 90);      // 仅 90/180/270
flip(srcPath, destPath, true);       // 水平翻转
crop(srcPath, destPath, 10, 10, 100, 100);
resizeExact(srcPath, destPath, 320, 240);

// 格式转换
convertFormat(srcPath, destPath, 'png', 100);

// 文档扫描：先透视校正（4 角点 TL→TR→BR→BL）拉正，再扫描增强成干净黑白
perspectiveCorrect(srcPath, warpPath, 40,30, 320,52, 305,440, 22,420, 600, 800);
scanEnhance(warpPath, destPath, 'bw'); // 'bw' 黑白二值 / 'gray' 灰度 / 'color' 彩色

使用前提（购买前请读）

  • 仅 App 端（app-android / app-ios）；H5、各家小程序不支持（原生库加载不了）。
  • 从插件市场获取的插件包已内置全部原生产物，买家无需任何本地构建。
  • 必须自定义基座或云打包：本插件含原生库，HBuilderX 标准基座跑不了 （报「找不到原生模块」属预期）。Android 真机调试：制作自定义调试基座（HBuilderX ≥ 4.26）；正式发行走云打包均可。
  • iOS 端原生库含 Swift，宿主原生工程需开启「支持 Swift」；离线打包按 DCloud 离线 SDK 常规流程集成。
  • aiImageEdit 等 4 个 AI API 走 UTS 网络层，需自配 AI 服务（填 AiImageConfig），不依赖本插件原生库。
  • 路径入参：请传绝对路径或 file:// URI（uni.chooseImage 的 tempFilePath 原样可用，插件内置规范化）； _doc/ 等 uni 约定相对路径暂不解析（可自行用 UTSAndroid.convert2AbsFullPath 转换，后续版本内置）。
  • 验证状态（诚实声明）：核心算法 162 项自动化测试全绿；Android 已用云打包自定义基座在模拟器（arm64）端到端实测—— compressImage / grayscale / gaussianBlur / rotate / crop / convertFormat 六项代表性 API 逐个点验全过 （输出为 progressive JPEG、等比/裁剪尺寸精确核验），file:// URI 直传含回归测试； iOS 集成编译迭代中，整包集成建议先用 demo 工程试跑再上生产。
  • 最终 App 打包由 HBuilderX / @dcloudio CLI 完成。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

无

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件不采集任何数据。所有计算/处理均在本地完成，无任何网络请求、不发送数据到任何服务器。

3. 本插件是否包含广告，如包含需详细说明广告表达方式、展示频率：

无

评论列表 撰写评论 向官方投诉

暂无用户评论。