更新记录

2.6.3（2026-09-24）

• 注意（App-Android / uni-app x）：UTS 编译到 Kotlin 后端时不生成可选参数的默认值，调用可选参数的 API 需显式传全， 例如 findContours(id, 'external', 'simple')、warpAffine(id, m, 0, 0)、distanceTransform(id, 0)、boxFilter(id, 9, 1)； 省略会报 No value passed for parameter 'xxx'。传入的值与各端实现里 ?? 的默认值相同，故结果与省略时一致。 iOS / web / 小程序 / 鸿蒙后端不受此限制。

• App 端（iOS / Android）路径兼容：loadImage 现在能直接接受 uni-app x 的虚拟路径与包内资源路径 —— unifile://...（如 uni.env.USER_DATA_PATH）、/static/...、static/...、_www/... 会先经 UTSiOS.convert2AbsFullPath / UTSAndroid.convert2AbsFullPath 转成真实文件路径； http(s)、data:、file:// 与普通绝对路径行为不变（原样透传）。 这样 App 端「内置示例图」这类包内静态资源也能直接加载，不必再依赖相册。

• 说明：unifile:// 是运行时虚拟 scheme（实测 uni.env.USER_DATA_PATH = unifile://usr/）， 原生 OpenCV 无法直接读取，故在插件侧统一转换。

• 版本依赖：App 路径兼容在 Android 侧依赖 UTSAndroid.convert2AbsFullPath（uni-app x 3.90 起 / uni-app 的 UTS 插件内可用）， iOS 侧依赖 UTSiOS.convert2AbsFullPath（uni-app x 4.11 起；本插件整体要求 HBuilderX ≥ 4.61，已覆盖）。 iOS 端转换先于 Android 侧落地（两次提交），对本版使用者无差别。

2.6.2（2026-09-23）

鸿蒙端交付改造：源码授权版零配置；插件包鸿蒙体积 22MB → 9MB

• 源码授权版鸿蒙端：零配置。插件包不再散放裸 .so，改为随包提供只含原生库的载体 har （utssdk/app-harmony/libs/opencv-image-libs.har，9MB，内含 arm64-v8a + x86_64 两套 libopencv_bridge.so / libc++_shared.so），并在插件 utssdk/app-harmony/config.json 中声明该依赖 —— HBuilderX 生成鸿蒙工程时会自动把 har 拷入模块目录、按 config.json 生成模块 oh-package.json5， ohpm 再解包其中 libs/** 合并进应用。

  事项	之前（≤2.6.1）	现在（2.6.2）
  买家要做什么	手动把 utssdk/app-harmony/libs/<ABI>/*.so 同步到工程 harmony-configs/entry/libs/<ABI>/	什么都不用做（仅需工程自带 EntryAbility）
  插件包鸿蒙部分	裸 .so 22MB	载体 har 9MB
  源码改动是否仍生效	生效	生效（源码流程编译源码，har 只提供原生库）

• ⚠️ 普通授权版（加密包）的鸿蒙端不支持 —— 受 DCloud 官方限制：官方规则为 "发行平台为 web / 小程序 / 鸿蒙时，UTS 加密插件需云端编译，目前仅支持 uni-app x 项目，不支持 uni-app 项目"； HBuilderX 中该分支由 isX（UNI_APP_X === "true"）守卫，uni-app(Vue2/Vue3) 工程不触发。 需要鸿蒙请选择源码授权版。

• 升级提示：

  • 若你此前按旧文档把 .so 复制到了工程 harmony-configs/entry/libs/，可以删除（不再需要，也不影响构建）。
  • 鸿蒙端 API、数值与行为完全不变（OpenCV 4.9.0 内核未动；真机全序列与 2.6.1 基线一致）。

• 引擎仍为 OpenCV 4.9.0，API 数量不变（77）。

2.6.1（2026-09-22）

新增：H5 / 微信小程序 纯 JS 入口（普通授权版五端可用性恢复）

DCloud 加密 UTS 插件的解密只发生在 App 云打包；uni-app(Vue2/Vue3) 工程的 H5 / 微信小程序 端在本地编译时无法解密加密 .uts（官方规则：加密插件 web/小程序/鸿蒙需云端编译且仅支持 uni-app x）。本版为两个平台提供随包明文 JS 入口，API 与 UTS 完全同名同参、返回值一致：

• 导入方式见 README「授权与交付」的条件编译示例；App 端仍走 UTS 入口（云打包），导入路径不变。
• js_sdk 明文入口的 API 签名由 utssdk/web/index.uts 真源机械生成（生成脚本 + 签名护栏 + 双引擎运行时等价验证，同一输入两引擎输出逐字节一致），后续版本随 UTS 同步再生成。
• 对既有源码授权版用户：无任何行为变化，无需迁移。
• 引擎仍为 OpenCV 4.9.0，API 数量不变（77）。

平台兼容性

uni-app(3.8.4)

uni-app x(4.0)

其他

OpenCV 图像识别 - uni-app 跨端图像处理插件

基于 OpenCV 4.9.0 的 uni-app UTS 插件，句柄式图像处理管线。一套 API 覆盖 App-Android / App-iOS / 鸿蒙 / H5 / 微信小程序，同一输入各端结果一致；全部运算在设备本地完成，不上传任何数据。

支持 uni-app（Vue2 / Vue3）与 uni-app x 工程。

uni-app x 实测情况（同一插件包直接用于 x 工程，无需改动）：

x 工程注意： ① 页面用 .uvue。算法实现按端分流：H5 / 微信小程序走 js_sdk/**（明文 JS），App 三端与鸿蒙走 utssdk/app-* 原生实现（js_sdk 并非「仅 uni-app 可用」，x 的 H5/mp 同样依赖它）； ② x 的 App 端长内容需放进 <scroll-view>；③ 小程序端取画布节点要传 res[0].node； ④ App 端「内置示例图」：页面用 uni.getFileSystemManager() 把包内 static/sample/*.png 复制到 uni.env.USER_DATA_PATH（unifile://usr/），插件的 iOS / Android 侧用 UTSiOS.convert2AbsFullPath / UTSAndroid.convert2AbsFullPath 转真实路径后加载（该路径兼容自 2.6.3 起；UTSiOS.convert2AbsFullPath 要求 HBuilderX ≥ 4.11，本插件整体要求 ≥ 4.61，已覆盖）； ⑤ App-Android（uni-app x / Kotlin 后端）必须显式传全可选参数：UTS 编译到 Kotlin 时不生成默认值， warpAffine(id, m)、findContours(id)、distanceTransform(id)、boxFilter(id) 这类省略可选参数的写法会报 No value passed for parameter 'xxx'。按各端实现里 ?? 的默认值显式传即可（如 findContours(id, 'external', 'simple')、warpAffine(id, m, 0, 0)），数值与省略时完全一致。 iOS/Swift、web、小程序、鸿蒙四个后端不受影响（可选参数正常）。 ⑥ 用插件市场加密包时，x 的 web 端会打印一条 warning: File '…/uni_modules/axen-opencv-image/utssdk/web/index.uts' is not a module —— 这是加密后该文件变 二进制、编译器按模块解析失败所致；H5 的实际代码走 js_sdk/**，功能与数值不受影响，可忽略。

✨ 特性

• 🖼️ 基础处理：灰度、HSV 转换、二值化、高斯模糊、缩放、Canny 边缘
• ✏️ 绘图标注：矩形 / 圆形 / 直线 / 中文与英文文字标注（putText）
• 🔬 卷积滤波：自定义卷积核 filter2D / Sobel / Scharr / Laplacian 边缘检测（1.2.0）
• 🎯 自动阈值：OTSU / 三角法自动计算最优阈值（返回阈值与新句柄，1.2.0）
• 📐 霍夫变换：直线检测（HoughLinesP）/ 圆检测（HoughCircles），返回检出元素 JSON（1.2.0）
• 🔷 轮廓与形状识别：面积、外接矩形、顶点数、形状分类（circle/rectangle/triangle/quad/other）
• 📐 轮廓进阶：凸包、多边形逼近、最小外接圆、旋转矩形、轮廓层级树（1.3.0 / 2.2.0）
• 🔀 几何变换：仿射 / 透视变换、图像金字塔上/下采样（1.3.0）
• 🌈 颜色空间扩展：LAB / XYZ / YCrCb 转换、灰度转彩、通道拆分 / 合成（2.0.0）
• ⚡ 增强与像素运算：CLAHE、加权融合、convertScaleAbs、位运算（与/或/异或/非）、boxFilter、距离变换（2.0.0）
• 📊 直方图与连通域：直方图、反投影、相似度比较、连通域统计（2.1.0）
• 🔍 模板匹配：TM_CCOEFF_NORMED + NMS，返回 Top N 位置与分数
• 🧩 特征点匹配：ORB 提取 + BFMatcher(HAMMING) + 0.75 比率测试
• 🎨 伪彩与角点：applyColorMap（22 种色表）、cornerHarris、Shi-Tomasi 角点（2.4.0）
• 📱 二维码：生成 / 检测 / 解码 / 一步检测解码，五端可用（2.5.0）
• 🔄 几何增强与句柄管理：任意角度旋转 rotate、ROI 裁剪 getRoi、图像尺寸 imageSize、多尺度模板匹配 matchTemplateMultiScale、批量释放 releaseAll（2.6.0）
• 🏗️ 句柄模型：loadImage 返回句柄，链式处理不拷贝原图，用完必须 releaseImage
• 🔒 本地计算：所有图像处理均在设备本地完成，不上传任何数据

引擎（Android / iOS / 鸿蒙为原生 OpenCV 4.9.0，H5 与微信小程序为 WebAssembly）随插件内置，导入即可用，无需自行编译或额外下载。

📦 安装

插件市场搜索「OpenCV 图像识别」，或直接把 uni_modules/axen-opencv-image 导入项目。安装后无需 npm install、无需 CocoaPods。

环境要求：HBuilderX ≥ 4.61；Android API ≥ 21；iOS ≥ 12；微信小程序基础库 ≥ 2.14.0；鸿蒙 HarmonyOS NEXT。

🧾 授权与交付

• 普通授权版平台路由（DCloud 加密插件机制）：加密插件的解密编译只发生在 App 云打包 （云端传统打包，不支持安心打包 / 离线打包）。App（Android/iOS）端照常从 UTS 插件入口导入； H5 / 微信小程序端因本地无法解密加密 .uts，请改从随包附带的明文 JS 入口导入 （API 与 UTS 完全同名同参、返回值一致，见下方条件编译写法）。 ⚠️ 鸿蒙端：仅源码授权版支持；普通授权版（加密包）不支持 —— 受 DCloud 官方限制。 官方规则明确：若发行平台为 web、小程序或鸿蒙，UTS 加密插件需提交云端编译，目前仅支持 uni-app x 项目， 不支持 uni-app 项目；HBuilderX 实现上该云编译分支由 isX（UNI_APP_X === "true"）守卫， uni-app(vue2/vue3) 工程不会触发，因此加密包在鸿蒙端没有可用的编译路径（与插件实现无关）。 需要鸿蒙请选择源码授权版，详见「鸿蒙」章节。

普通授权版五端导入写法（条件编译）：

// App（Android/iOS，云打包由 DCloud 云端解密，UTS 入口）
// #ifdef APP-PLUS || APP-HARMONY
import { initEngine, loadImage, cvtGray, findContours, releaseImage } from '@/uni_modules/axen-opencv-image'
// #endif

// H5（浏览器，明文 JS 入口）
// #ifdef H5
import { initEngine, loadImage, cvtGray, releaseImage } from '@/uni_modules/axen-opencv-image/js_sdk/index.js'
// #endif

// 微信小程序（明文 JS 入口；onReady 后需先 bindProcessingCanvas(canvas)，与 UTS 版要求一致）
// #ifdef MP-WEIXIN
import { initEngine, loadImage, bindProcessingCanvas, cvtGray } from '@/uni_modules/axen-opencv-image/js_sdk/mp-index.js'
// #endif

• 源码授权版：全端直接使用 UTS 入口，无需上述分流；JS 入口签名与 UTS 完全一致。
• ⚠️ 鸿蒙平台标识是 APP-HARMONY（不是 APP-PLUS）：条件编译漏写它会导致鸿蒙下所有分支 都不匹配、插件 API 全部 undefined（表现为能选图但页面无任何反应、控制台无插件日志）。
• ✅ 鸿蒙端（源码授权版）：零配置。插件包内 utssdk/app-harmony/libs/opencv-image-libs.har 是只含两个 ABI .so 的载体 har，插件用 utssdk/app-harmony/config.json 自动声明该依赖 —— HBuilderX 生成鸿蒙工程时会把它写进模块的 oh-package.json5，ohpm 再解包其中的 .so 合并进应用。 你只需要：① 工程提供 EntryAbility；② 条件编译写 APP-PLUS || APP-HARMONY，不用拷任何 har、不用改依赖。
  • 为什么载体 har 要单独起名：ohpm 规定"包不能依赖与自己同名的包"（00618004 Same As The PkgName）， 而插件模块名就是 @uni_modules/axen-opencv-image，所以载体 har 的内部包名为 @axen/opencv-image-libs。
  • ⚠️ 普通授权版（加密包）的鸿蒙端不支持 —— 受 DCloud 官方限制（加密插件的鸿蒙端需云端编译，官方仅支持 uni-app x 项目）；鸿蒙仅源码授权版可用。
• ⚠️ App 端必须用「自定义调试基座」或云打包运行（普通授权版，已实测）：本插件是第三方 UTS 插件， 标准基座不含它，且加密 .uts 无法在本地解密，因此用标准基座运行必然"点按钮没反应"、 控制台没有任何 [opencv-demo] 日志——这不是插件故障，是加密机制决定的。正确方式：
  • 调试：HBuilderX → 运行 → 制作自定义调试基座（基座由云端构建、会解密插件）→ 运行到手机
  • 发布：云打包（传统打包）出 APK/IPA
  • 两条路径已在 Android 真机实测通过（2026-09-20，全序列命中 Android 原生族基线）
• ⚠️ 选图功能需勾选 App 模块（与插件无关的通用配置）：若你的页面用 uni.chooseImage 选图， 必须在 manifest.json → App 模块配置 勾选 Camera（相机） 与 Gallery（相册）： 自定义基座与云打包都按"已勾选模块"裁剪构建（标准基座才内置全部模块），未勾选时 iOS 端会提示 "打包时未添加 Gallery/Camera 模块"。改完模块必须重新制作自定义基座，旧基座不会自动生效。 iOS 模拟器无摄像头硬件，调试时建议 sourceType: ['album']（或直接用工程自带的示例图片按钮）。 iOS 还需在 manifest 填写 NSCameraUsageDescription / NSPhotoLibraryUsageDescription 隐私描述。
• 两种授权均绑定唯一的 appid 与包名；更换其中任一项需重新购买授权。
• 试用：可在自定义调试基座中评估全部功能；试用版本不能用于正式发布。
• 版本变更记录见插件包内 changelog.md。
• 企业定制、私有化部署或超出上述范围的使用，请通过插件市场联系方式沟通。

⚠️ App 云打包的项目体积门槛（60MB 免费额度，必读）

DCloud 云打包按【项目体积】计费（不是 APK/IPA 体积），免费额度 60MB。本插件的原生 OpenCV 产物较大 （iOS fat 静态库 48MB / Android aar 20MB / 鸿蒙载体 har 9MB / 明文 H5 引擎 5MB）， 各端产物全留 ≈ 84MB，必然超限。而云打包一次只打一个平台 —— 其余平台的产物纯属白占额度。

打包前按目标平台裁一刀即可（Android 单端 ≈27MB；iOS 单端需先裁切片，见下方提示）：

cd uni_modules/axen-opencv-image/utssdk

# 只打 Android：移出 iOS 与鸿蒙产物（可先备份到工程外）
mv app-ios app-harmony ../            # 打包完成后移回

# 只打 iOS：移出 Android 与鸿蒙产物
# mv app-android app-harmony ../

# 只打鸿蒙：无需裁（走本地构建，不涉及云打包额度）

• iOS 额外提示：内置 fat 库 = arm64（真机）+ x86_64（Intel Mac 模拟器），未裁前 48MB → iOS 单端 ≈53MB，贴着 60MB 上限；若只做真机发布，裁掉 x86_64 切片可降到 约 22MB （该副本不能再跑 x86_64 模拟器；Apple Silicon 上的 arm64 模拟器本就不含此切片）：

  cd uni_modules/axen-opencv-image/utssdk/app-ios/Libs/OpenCVBridge
  lipo -thin arm64 -output libOpenCVBridge.a libOpenCVBridge.a

• 上述裁剪只影响体积：被移出的平台产物不参与目标平台的编译，功能与数值完全不变。
• 若不想裁剪、且项目体积确实需要超过 60MB，只能在 DCloud 侧充值"App 大小超限"额度。

🚀 快速开始

import {
  initEngine, loadImage, releaseImage,
  cvtGray, threshold, cvtHsv, gaussianBlur, resize, canny,
  detectColorRange, findContours, matchTemplate, orbMatch,
  drawRect, drawCircle, drawLine, putText,
  filter2D, sobel, scharr, laplacian,
  thresholdOtsu, thresholdTriangle, houghLinesP, houghCircles,
  convexHull, approxPolyDP, minEnclosingCircle, minAreaRect,
  getAffineTransform, warpAffine, getPerspectiveTransform, warpPerspective, pyrUp, pyrDown,
  cvtLab, cvtXyz, cvtYCrCb, grayToBgr, splitChannels, mergeChannels,
  clahe, addWeighted, convertScaleAbs, bitwiseAnd, bitwiseOr, bitwiseXor, bitwiseNot,
  boxFilter, distanceTransform,
  qrEncode, qrDetect, qrDecode, qrDetectAndDecode,
  toBase64
} from '@/uni_modules/axen-opencv-image'

// 1. 初始化（首帧前调用一次；H5/小程序端会等待 wasm 编译完成）
await initEngine()

// 2. 加载图片，得到句柄
const img = await loadImage('/storage/emulated/0/xxx.png')   // App: 本地文件绝对路径
// App 端会自动兼容 `unifile://...`（如 uni.env.USER_DATA_PATH）与包内资源路径（`/static/...`、`static/...`、`_www/...`）
// const img = await loadImage('https://xxx/1.png')          // H5: URL / blob / data URL
// const img = await loadImage(wxTempPath)                   // 微信小程序: wx.chooseImage 临时路径，或 '/static/sample/xxx.png' 包内路径

// 3. 基础处理：灰度 -> 二值化
const gray = cvtGray(img)
const binary = threshold(gray, 127, 255)

// 4. 颜色检测（输入 HSV 图，范围为 OpenCV 约定 H:0-180, S:0-255, V:0-255）
const hsv = cvtHsv(img)
const red = detectColorRange(hsv, 0, 100, 100, 10, 255, 255)

// 5. 轮廓/形状识别（输入二值图）
const contours = JSON.parse(findContours(binary))   // [{ area, x, y, width, height, shape, points }]

// 6. 模板匹配（templateId 为模板图句柄，需先 loadImage 模板图）
const templateId = await loadImage('/path/to/template.png')
const matches = JSON.parse(matchTemplate(img, templateId, 3))   // [{ x, y, width, height, score }]

// 7. 特征点匹配（imgB 为另一张图的句柄）
const imgB = await loadImage('/path/to/another.png')
const orb = orbMatch(img, imgB)   // { keypoints1, keypoints2, matches, goodMatches }

// 8. 绘制结果并导出 base64 展示
drawRect(img, matches[0].x, matches[0].y, matches[0].width, matches[0].height, '#00ff00', 3)
const b64 = await toBase64(img)

// 9. 释放句柄（所有中间结果都要释放）
releaseImage(img); releaseImage(gray); releaseImage(binary); releaseImage(hsv); releaseImage(templateId); releaseImage(imgB)

⚠️ 句柄模型：每个处理函数返回新句柄，原句柄不受影响；用完必须 releaseImage 释放，否则内存持续增长（H5 / 小程序端是 WASM 线性内存，泄漏最终会导致可分配内存耗尽）。批量处理循环里请逐个释放。

📖 API 文档

返回类型定义见 utssdk/interface.uts。

返回值为 JSON 字符串的接口（findContours / matchTemplate / matchTemplateMultiScale / houghLinesP / houghCircles / convexHull / approxPolyDP / minEnclosingCircle / minAreaRect / getAffineTransform / getPerspectiveTransform）各端统一返回字符串，请 JSON.parse 后使用；其余接口返回对象或数字句柄。

🌐 平台支持

各端结果一致：同一张图在五端的阈值、轮廓数、霍夫检出、模板分数等指标逐项相同。仅 wasm 端与原生端在少数浮点敏感指标上存在末位差异（如霍夫直线 2147 vs 2151、模板分数 0.492 vs 0.519），源于向量化内核的浮点归约顺序，不影响阈值判定与业务结论。

uni-app x · iOS 实测（照片 1440x2560）：轮廓 4967、层级树 15·顶1·深1、ORB 500·500、 直线 2147、圆 30 @(973,1470) r=198（约 0.5s）、连通域 1（a=3686377）、QR [449,28] 解码成功、 凸包/逼近/外接圆(r=1468)/旋转矩形(2559x1439 90°)、OTSU 155.0、三角法 78.0 —— 与 wasm 族基线逐项一致 （该端为原生 OpenCV，因此直线取 2147 而非 arm64 族的 2151、模板分数取 0.519 而非 wasm 的 0.492）。

内置示例图（400x300）同端实测：轮廓 23、模板 0.873@[55,75]、ORB 297·295、连通域 120000、 OTSU 150.0、三角法 253.0、直线 412、圆 0、凸包 119301、外接圆 r=249、旋转矩形 299x399。 App 端「内置示例图」可用（页面物化到 uni.env.USER_DATA_PATH + 插件侧路径转换，见下方 x 注意事项 ④）。

⚠️ 各端使用注意

微信小程序

• 必须绑定画布：页面 onReady 后调用 bindProcessingCanvas(canvas)（<canvas type="2d">），读图/写图走该画布；未绑定时 loadImage 会失败。
• 基础库 ≥ 2.14.0 时由 WXWebAssembly 原生解压加载 wasm；更早的基础库走字节回退加载，速度较慢。
• 引擎随插件自包含（uni_modules/axen-opencv-image/static/），宿主无需额外放置 wasm 文件。
• 请用发行模式打包：运行模式含 sourcemap 会显著增大包体，容易超过预览/上传限制。
• 首次初始化耗时约几百毫秒（wasm 编译），建议在首页启动时 initEngine() 一次，复用后续调用。

Android

• 需自定义调试基座：HBuilderX → 运行 → 运行到手机或模拟器 → 制作自定义调试基座。
• 图片格式支持 JPEG / PNG / WEBP / TIFF / EXR / JPEG2000；读取相册或拍照由宿主调用 uni.chooseImage（插件不新增权限）。
• 宿主注意（相册 / 相机）：App 端 uni.chooseImage 依赖原生 Camera&Gallery 模块 （HBuilderX 3.6.11+ 为可选模块）。两点都要满足：① manifest.json 的「App 模块配置」勾选 Camera&Gallery （模块标识 Camera）；② 调试基座/安装包里确实链接了该模块——缺任一项，运行时会提示 「打包时未添加 Camera 模块」。H5 与小程序端不需要该配置（H5 走浏览器文件选择器）。
• 64 位产物已按 16KB 页对齐，满足 Google Play 上架要求。

iOS

• 引擎已内置，无需 CocoaPods、无需额外配置；内置桥接库含 arm64（真机）与 x86_64（模拟器） 两种切片，支持 iOS 12 及以上。
• 已在 iPhone 真机与模拟器完成全量功能验证（2.6.0 真机基座 71 次霍夫圆连打零漂移零崩溃）；若你的环境需要其它切片组合（例如 Apple 芯片 Mac 上的 arm64 模拟器），可通过插件市场联系方式获取支持。

鸿蒙

源码授权版：零配置。 插件包内只有一个载体 har（只含 .so），由插件 config.json 自动声明依赖：

utssdk/app-harmony/
├── config.json                          {"dependencies":{"@axen/opencv-image-libs":"./libs/opencv-image-libs.har"}}
└── libs/opencv-image-libs.har      9.02MB，内含 arm64-v8a / x86_64 两套
                                          libopencv_bridge.so + libc++_shared.so

HBuilderX 生成鸿蒙工程时会：

1. 把该 har 连同插件文件一起拷进模块目录（sync('**/*.{ets,js,har,tgz}')）；
2. 依据 config.json 生成模块的 oh-package.json5（parsePackageDeps 按 utssdk/app-harmony/ 解析相对路径）；
3. ohpm install 把 har 内的 libs/** 解包到 oh_modules 并合并进应用。

所以你不需要在工程里放任何 har、也不需要改依赖，只要让应用使用自己的 EntryAbility （参考演示工程 harmony-configs/entry/src/main/ets/entryability/），并把条件编译写成 APP-PLUS || APP-HARMONY。

⚠️ 普通授权版（加密包）不支持鸿蒙 —— 受 DCloud 官方限制：官方规则为 "发行平台为 web / 小程序 / 鸿蒙时，UTS 加密插件需云端编译，目前仅支持 uni-app x 项目，不支持 uni-app 项目"； HBuilderX 中该云编译分支由 isX（UNI_APP_X === "true"）守卫，uni-app(vue2/vue3) 工程不触发， 因此加密包在鸿蒙端无可用编译路径。两种表现： ① 若工程在 APP-HARMONY 下 import 了本插件 → 鸿蒙构建在 ohpm 阶段失败 （.../utssdk/app-harmony/module.har does not exist）； ② 若按建议做条件编译（鸿蒙端不 import，仅在 APP-PLUS/APP-HARMONY 之外引入 UTS 入口）→ 构建与运行正常，插件能力不可用，页面可自行给出提示 （演示工程即此做法，实测：构建成功、启动后提示"鸿蒙端不支持…仅源码授权版可用"）。 鸿蒙请使用源码授权版（本文档上一节即为其零配置接入方式）。

❓ 常见问题

Q：图片加载返回 -1？ 路径写法随平台不同：App 用本地文件绝对路径（如 /storage/emulated/0/xxx.png），H5 用 URL / blob / data URL，微信小程序用 wx.chooseImage 临时路径或包内 /static/... 路径；小程序端还需先 bindProcessingCanvas。

Q：内存一直涨 / 后面开始报错？ 句柄未释放。每个函数都返回新句柄，包括 cvtGray、threshold、mask 这类中间结果，用完即 releaseImage；循环里尤其注意。

Q：模板匹配分数偏低？ 分数受输入像素与算法实现影响，判阈值请按业务实测标定；同图在不同引擎（原生 / wasm）可能有约 0.03 的末位差异，命中位置一致。

Q：findContours 返回的 JSON 很大？ 轮廓点集默认带全部点。数千条轮廓时请改用 convexHull / approxPolyDP 取精简点集，或用 findContoursHierarchy 只看层级与统计。

Q：小程序预览/上传提示超限？ 切到发行模式重新编译；运行模式含 sourcemap，包体会明显变大。

Q：二维码解码失败？ 被解图里二维码模块需 ≥ 10 像素；模块过小时先用 resize 放大再解码。qrDetect 可先确认能否检出四角点。

Q：H5 首屏变慢？ 首次 initEngine() 需要编译约 5MB 的 wasm，属一次性成本；可放在启动页提前初始化并复用。

🗓️ 路线图

当前 77 个 API（15 基础 + 8 个 1.1.0 + 11 个 1.2.0 + 10 个 1.3.0 + 15 个 2.0.0 + 5 个 2.1.0 + 1 个 2.2.0 + 3 个 2.4.0 + 4 个 2.5.0 + 5 个 2.6.0），覆盖经典图像处理与特征匹配的常用子集。后续规划：

性能建议（大图霍夫直线）

houghLinesP 在 OpenCV 里没有并行实现，耗时由角度分辨率与阈值主导。1440×2560 这类大图上：

• 把 thetaDeg 从 1 提到 2：约 7 倍提速，检出线条数基本不变（实测 2033 → 2110）；
• 把 threshold 从 80 提到 120：约 3 倍提速，线条数不变；
• 先自行 resize 到长边 1440 再检测、并把坐标乘以 1/scale 还原：10 倍以上，但线条数会按比例减少。

houghCircles 已按在线核数并行（Android 实测 1440×2560 上 6000ms → 2200ms）。

下个版本（2.7.0）计划

• 性能：32 位 ARM（armeabi-v7a）引擎优化与多线程放开 —— 低端 32 位真机上的耗时显著下降
• 二维码增强：qrDetectMulti / qrDetectAndDecodeMulti（一图多码）
• 几何与拼接：findHomography（含 RANSAC）配合特征匹配做透视校正 / 拼接
• 特征点增强：SIFT / AKAZE 特征 + FLANN 匹配
• 便捷能力：imencode / imdecode（处理完直接上传 / 落盘）
• 体验：大图自动降采样开关（opt-in）

2.6.0 已交付：多尺度模板匹配 matchTemplateMultiScale、任意角度旋转 rotate、ROI 裁剪 getRoi、图像尺寸 imageSize、批量释放 releaseAll（共 5 个新 API，总数 77）。

中期

• 人脸检测（Haar 级联或 YuNet ONNX）
• DNN 推理模块（ONNX：分类 / 检测 / 分割，模型由宿主下发）

远期

• 光流（稀疏 / 稠密）与背景建模（MOG2 / KNN）
• 视频流处理管线（各端相机帧回调接入）
• GPU 加速（OpenCL / Metal / 鸿蒙 NAPI 侧加速）

需求优先级欢迎通过插件市场联系方式反馈，将按热度排期。

🔐 隐私与安全

本插件所有图像处理均在设备本地完成，不主动采集 IDFA、定位、相机、麦克风、相册、通讯录信息，也不上传任何数据。处理图片由宿主业务方选择传入；读取相册/拍照需宿主自行调用 uni.chooseImage 申请用户授权，插件不新增权限。

📄 许可证

插件引擎基于 OpenCV（Apache License 2.0，含原始 OpenCV 与 opencv.js 组件），许可见 THIRD_PARTY_LICENSES.md；插件本体授权以插件市场页面/购买协议为准。