更新记录

1.0.0（2026-09-30） 下载此版本

首次发布。

• 三端统一 mpaasScan API：code / msg / result / scanType，兼容旧 Mpaas-Scan / resp_result 契约
• 三端识别层均为支付宝 mPaaS ***：

平台兼容性

uni-app x(5.26)

其他

uni-app x 原生扫码（三端统一 mpaasScan）

面向 uni-app x（含蒸汽模式） 的三端 UTS 扫码插件。统一 mpaasScan API 与结果契约，兼容旧版支付宝原生扫码插件（Mpaas-Scan / resp_result），方便从 uni-app 或旧云插件平滑迁移。

三端识别层均为支付宝 **mPaaS ***** 同源能力，业务侧只需调用同一 API，result / scanType / 错误码三端一致。

功能特性

平台兼容性

• HBuilderX：^4.31.0
• uni-app x：App-Android / App-iOS / App-HarmonyOS（含蒸汽模式）

快速开始

import { mpaasScan } from '@/uni_modules/bin-mpscan'

mpaasScan({
  scanType: ['qrCode'],
  success: (res) => {
    console.log(res.result)   // 扫码内容
    console.log(res.scanType) // qrCode | barCode
  },
  fail: (err) => {
    // 9050003 为用户取消，一般可忽略
    if (err.errCode !== 9050003) {
      uni.showToast({ title: err.errMsg, icon: 'none' })
    }
  }
})

提交/绑定类入口建议配合防重复点击（如 throttle）再调用。

API

mpaasScan(options)

一次性全屏扫码，回调触发一次后结束。

Options

Result

错误码

fail 回调参数继承 UniError，业务可读 err.errCode / err.errMsg。

接入配置（必读）

Android / HarmonyOS / iOS 使用阿里云 **mPaaS「*」，鉴权与 应用包名 + 签名 绑定。必须换成你自己在 mPaaS 控制台创建的应用配置。插件内配置已做隐私脱敏（AppId / License / 包名均为占位符如 YOUR_MPaaS_APP_ID、com.example.app），无法通过其它包名校验，运行前务必替换。

1. 开通 mPaaS

1. 开通 mPaaS，创建应用并下载 Android / HarmonyOS 配置（填包名、指定签名）。
2. 按下文分别替换 Android meta-data iOS meta.config 与鸿蒙 mpaas.config。

2. Android 配置

打开 uni_modules/bin-mpscan/utssdk/app-android/AndroidManifest.xml，填入 meta-data：

• 制作自定义基座 或云打包后验证
• License 验证失败时清除应用数据再测（每日约校验一次）

3. HarmonyOS 配置

1. 替换 utssdk/app-harmony/resources/rawfile/mpaas.config（packageName 与 manifest.json → app-harmony → distribute → bundleName 一致）
2. 构建机 ohpm 需配置 mPaaS 源（%USERPROFILE%/.ohpm/.ohpmrc 或 ~/.ohpm/.ohpmrc）：

@mpaas:registry=https://mpaas-ohpm.oss-cn-hangzhou.aliyuncs.com/meta
@alipay:registry=https://mpaas-ohpm.oss-cn-hangzhou.aliyuncs.com/meta

3. 可选：与其它自带 OpenSSL 的 SDK 同时使用时，hvigor 可能报 Duplicated files found in module entry，可在 DevEco entry/build-profile.json5 的 buildOption 增加：

"nativeLib": {
  "filter": {
    "pickFirsts": ["**/libcrypto.so", "**/libssl.so"]
  }
}

4. iOS 说明

• 使用 utssdk/app-ios/ 内置 mPaaS 静态闭包（Libs/ + Resources/）
• 替换 utssdk/app-ios/meta.config 与 utssdk/app-ios/Resources/meta.config（两份需一致）：appId / appKey / bundleId / mpaasConfigLicense 等，与控制台下载的 iOS 配置一致；bundleId 须等于应用 BundleId
• 不要配置 dependencies-pods 拉 mPaaS：缺 TBScan/PSD 符号，且可能丢 DCloudUTSFoundation
• UTS.xcconfig 已配 -ObjC + force_load MPScanModule（保证 Category 入口）

5. 打包运行

Android 私有 libc++ 隔离

libdecode1002235b60ba.so（mascanengine）为 NDK r18b 产物，异常展开必须走同套 libc++。与 uni-app x 基座共用 libc++_shared.so 会在 isualead::Exception unwind 时 SIGSEGV。

隔离做法：

1. 取 mPaaS 官方 com.mpaas.commonlib:libcshared-build 的 arm64 libc++_shared.so（与 mascanengine 10.2.3.x 同套，源文件已 vendored 到 ools/mpscan-cxx/）。
2. 改 DT_SONAME / 文件名为 libmpcxx.so（名字必须 ≤ 15 字节才能原地改 dynstr）。
3. 把 libdecode 的 DT_NEEDED libc++_shared.so → libmpcxx.so。
4. 两份 so 一并打进 mascanengine AAR 的 jni/arm64-v8a/。libdecode 的 C++ UND 会优先绑到私有 so，不再吃基座那份异常运行时。

真机回归：扫中、取消、相册选图、连续进出扫码页。

打包自检（必看）

私有 so 进包与否，看扫码日志：

• probe libmpcxx load OK + libs=...libmpcxx.so... → 隔离已生效
• probe libmpcxx load FAIL / 列表无 libmpcxx.so → 仍在跑旧包，必须重新制作自定义调试基座

libmpcxx 通过 独立 AAR libs/libmpcxx-build-10.2.3.51.aar 与 mascanengine 内嵌 jni 双路打进包。只改源码、只点「运行」不会更新原生 so。

权限

插件已在各端 Manifest / Info.plist / module.json5 声明，宿主商店隐私协议需写明相机用途。

注意事项

• 仅 App（Android / iOS / HarmonyOS），不支持 Web / 小程序。
• License 三端强制：扫码前校验配置完整性与身份绑定，失败回 9050009。Android/鸿蒙另有框架内 RSA 校验；iOS 额外校验 meta.config 的 bundleId 与当前应用一致。
• 相册识别：走 mPaaS 原生扫码页相册入口（hideAlbum 控制显隐），非自研解码。
• Android：插件内置 mPaaS 解码 AAR 已做 libc++ 符号隔离，兼容新版 uni-app x 基座；请勿用官方原版 mascanengine 覆盖 libs/。
• HarmonyOS：@mpaas/scanapp 无取消回调，返回原页时补发 9050003；scanType 固定 qrCode。
• iOS：识别类型为 QR + 常见一维码（EAN/UPC/Code128 等）；meta.config 需随包（已放 app-ios/Resources/meta.config）。
• 扫码分析不上报：插件不强制调用埋点/分析上报；如需 mPaaS「扫码分析」大盘，数据由原生引擎在 License 有效时自行产生，插件层不额外强制上报。
• 插件无广告；mPaaS 隐私政策见阿里云。
• 失败不会自动回退 uni.scanCode；需要回退时在 fail 里自行调用。

FAQ

Q：Android 真机弹「mPaaS Config License 验证失败」？
A：AndroidManifest.xml 的 meta-data 与包名/签名不一致（常见漏 workspaceId，或换包名未重新下载配置）。改完必须重做自定义基座；复验可清应用数据。

Q：Android 扫码页闪退 / logcat SIGSEGV？
A：常见两种：

1. 覆盖了插件内 mascanengine AAR（丢了 libc++ 相关处理）。
2. ScanRecognize 线程 libdecode*.so / isualead::ReaderSDK::readImage 崩溃：该 so 为 NDK r18b 产物，原先动态依赖 libc++_shared.so，与新版 uni-app x 基座 libc++ 异常 ABI 不兼容时抛 isualead::Exception 展开会 SIGSEGV。已做私有 libc++ 隔离（见下节），AI/visualead 增强识别保持开启。

Q：鸿蒙 x86_64 模拟器不能用？
A：官方 so 仅 arm64，请用真机；模拟器会回 9050006。

Q：能否和 uni.scanCode 混用？
A：可以。本插件失败不自动回退；需要回退时在 fail 里自行调用 uni.scanCode。

Q：如何做英文界面？
A：language: 'en'，或直接把业务文案传入 tipText / openTorchText / closeTorchText。

从旧插件迁移

旧工程常见写法：

const mpaasScanModule = uni.requireNativePlugin('Mpaas-Scan-Module')
mpaasScanModule.mpaasScan({ ... }, (ret) => {
  const url = ret.resp_result
})

改为：

import { mpaasScan } from '@/uni_modules/bin-mpscan'
mpaasScan({
  success: (res) => {
    const url = res.result // 对应 ret.resp_result
  }
})

目录结构

uni_modules/bin-mpscan/
  package.json
  readme.md
  changelog.md
  utssdk/
    interface.uts          # 类型与 API
    texts.uts              # 中英文默认文案
    unierror.uts           # 错误码实现
    app-android/           # mPaaS MPScan + AAR
    app-ios/               # mPaaS 静态闭包 Libs + Resources
    app-harmony/           # @mpaas/scanapp

许可与免责

• 插件代码：MIT
• 内含 mPaaS Android AAR / HarmonyOS ohpm 包版权归蚂蚁集团，遵循阿里云 mPaaS 服务协议；商用请自行开通并合规使用
• 使用本插件产生的业务与合规责任由接入方自行承担