更新记录

1.0.6（2026-09-06）

• 修复 uni-app x Android 示例调用微信注册与打开小程序 API 时的 SDK 参数类型推断编译错误。

1.0.5（2026-08-07）

• 重构客户 README，按“特色与场景、接入选择、最小注册、基础能力、常用业务、支付与高级能力、完整 API”顺序由浅入深引导接入。
• 补充登录、文本/网页/图片/小程序分享、打开小程序与客服、支付、商家转账、微信回流和兼容对象的完整回调示例。
• 增加 iOS Universal Link、AASA、URL Scheme、Associated Domains 和 9014108 的接入前检查与常见问题说明。
• 将 uni-app 与 uni-app x 示例统一升级为“微信能力控制台”，按操作顺序聚合配置、业务能力、状态提示和运行日志，改善移动端阅读与点击体验。
• README 使用通用占位配置并保持发布资料边界；本次仅更新文档、示例页面与发布元数据，不涉及原生源码，已安装匹配基座无需因本次升级重新制作。

1.0.4（2026-08-06）

• 修复 iOS 将强类型回调参数对象转换为 UTSJSONObject 时可能触发不可捕获类型转换异常、导致能力矩阵页面闪退的问题。
• iOS 成功、失败和完成回调改为强类型安全派发，保留客户传入 success / fail / complete 的真实调用方式。
• Android 与 iOS 注册状态改为以微信 SDK 的真实注册结果为准；重新注册前会清理缓存状态，失败 AppID 不再被误报为已注册。
• 本次修改涉及 Android/iOS 原生实现，升级后必须重新云打包或重新制作并安装对应平台自定义基座。

平台兼容性

uni-app(4.84)

uni-app x(4.84)

# lizhao-***-kit

lizhao-***-kit 是面向 uni-app 与 uni-app x 的微信开放能力 UTS API 插件，用一套调用方式接入 Android/iOS 微信注册、登录、分享、支付、商家转账、打开小程序、客服和回流监听。

插件简介

• 插件名：lizhao-***-kit
• 插件类型：UTS API 插件
• 调用环境：uni-app / uni-app x
• 导入路径：@/uni_modules/lizhao-***-kit

功能特色

• 统一公开 API：业务代码只调用 register / login / share / pay 等统一名称，不需要判断 registerByAndroid 或 registerByIos。
• 覆盖常见微信业务：支持授权登录、文本/图片/网页/小程序分享、支付、商家转账确认、打开小程序、打开客服和微信回流监听。
• 真实能力状态：注册结果、微信安装状态和 API 支持状态来自微信 SDK，不用静态值伪造成功。
• 完整回调契约：异步 API 支持 success / fail / complete，Android 与 iOS 使用一致的业务回调语义。
• 明确失败边界：统一错误码 9014101~9014111，未安装微信、未注册、参数错误、用户取消和签名配置错误可分别处理。
• 双项目兼容：同一插件 API 同时服务 uni-app 与 uni-app x，平台不支持时返回明确错误而不是静默失败。

适用场景

• App 使用微信授权登录，并将临时 code 交给业务服务端换取登录态。
• 将文字、图片、网页、音乐、视频、文件或小程序卡片分享给微信好友、朋友圈或收藏。
• 从 App 打开指定微信小程序页面，适用于商城、会员、活动和服务闭环。
• 接入微信支付或商家转账用户确认，前端只负责向微信提交服务端生成的参数。
• 打开微信客服会话，或监听用户从微信返回 App 时携带的回流数据。
• 同一业务同时维护 Android/iOS、uni-app/uni-app x，希望复用一套接口和错误处理逻辑。

接入方式选择

支持平台

安装说明

import * as ***Kit from '@/uni_modules/lizhao-***-kit'

业务代码只能调用下方 API 列表中的统一公开名称。不要直接调用 registerByAndroid、registerByIos 或其他 *By平台 函数；这些函数是插件内部委派入口，参数签名不属于客户接入契约。

接入前准备

1. 在微信开放平台创建并审核移动应用，取得 wx 开头的移动应用 AppID。
2. Android 端确保最终包名和应用签名与开放平台一致；iOS 端确保 Bundle ID、URL Scheme、Universal Link 和 Associated Domains 完整配置。
3. 使用包含本插件原生依赖的自定义基座或云打包安装包，标准基座和资源热更新不能新增微信 OpenSDK。
4. 在真实安装了微信的设备上测试。模拟器可验证参数和失败回调，但不能代替登录、分享、支付等真实微信链路。
5. 支付、商家转账和登录换取会话等敏感操作必须由业务服务端参与，禁止在客户端保存 AppSecret、商户密钥或私钥。

五分钟最小接入

先完成 SDK 注册，再读取能力矩阵。这个示例适合作为接入后的第一个验证点：

import * as ***Kit from '@/uni_modules/lizhao-***-kit'

***Kit.register({
  appId: 'wx1234567890abcdef',
  // Android 可传空字符串；iOS 必须填写已完成 AASA 配置的 HTTPS Universal Link。
  universalLink: 'https://your.domain.com/app/',
  success(registerResult) {
    console.log('微信 SDK 注册成功', registerResult)

    ***Kit.getApiSupportInfo({
      success(info) {
        console.log('微信能力矩阵', info)
      },
      fail(err) {
        console.error('读取能力矩阵失败', err)
      },
      complete(result) {
        console.log('能力矩阵检查完成', result)
      }
    })
  },
  fail(err) {
    console.error('微信 SDK 注册失败', err)
  },
  complete(result) {
    console.log('微信 SDK 注册流程完成', result)
  }
})

注册成功只表示当前 App 已通过微信 SDK 注册校验，不代表用户已经登录，也不代表支付或分享业务已经完成。后续能力必须分别调用对应 API。

基础能力

判断微信是否安装及版本能力

isInstall 和 isWXAppSupportApi 是同步方法，可用于控制按钮是否可用：

const installed = ***Kit.isInstall()
const supportTargetApi = ***Kit.isWXAppSupportApi(0)

console.log('是否安装微信', installed)
console.log('是否支持目标 API', supportTargetApi)

传入的 API 级别由业务根据目标微信能力确定；不确定时优先使用 getApiSupportInfo 查看完整能力状态。

拉起微信客户端

***Kit.openWXApp({
  success(res) {
    console.log('已提交拉起微信请求', res)
  },
  fail(err) {
    console.error('拉起微信失败', err)
  },
  complete(res) {
    console.log('拉起微信调用完成', res)
  }
})

常用业务示例

以下示例均应在 register 成功后调用。

微信授权登录

***Kit.login({
  state: 'login-' + Date.now().toString(),
  success(res) {
    console.log('微信授权成功，临时 code =', res.code)
    // 将 res.code 发送给业务服务端，由服务端换取微信会话和业务登录态。
  },
  fail(err) {
    console.error('微信授权失败', err)
  },
  complete(res) {
    console.log('微信授权流程完成', res)
  }
})

不要在客户端使用 AppSecret 换取 access_token。state 应由业务生成并在服务端校验，避免授权结果被串用。

分享文本

***Kit.share({
  type: 0,
  scene: 0,
  text: '这是一段要分享给微信好友的文字',
  success(res) {
    console.log('文本分享请求成功', res)
  },
  fail(err) {
    console.error('文本分享失败', err)
  },
  complete(res) {
    console.log('文本分享流程完成', res)
  }
})

分享网页

***Kit.share({
  type: 3,
  scene: 0,
  title: '网页标题',
  desc: '网页内容摘要',
  href: 'https://example.com/article/1001',
  thumbImageUrl: '/storage/emulated/0/Download/share-thumb.jpg',
  success(res) {
    console.log('网页分享请求成功', res)
  },
  fail(err) {
    console.error('网页分享失败', err)
  },
  complete(res) {
    console.log('网页分享流程完成', res)
  }
})

分享本地图片

***Kit.share({
  type: 1,
  scene: 0,
  imageUrl: '/storage/emulated/0/Download/share-image.jpg',
  thumbImageUrl: '/storage/emulated/0/Download/share-thumb.jpg',
  success(res) {
    console.log('图片分享请求成功', res)
  },
  fail(err) {
    console.error('图片分享失败', err)
  },
  complete(res) {
    console.log('图片分享流程完成', res)
  }
})

图片必须是当前 App 可以读取的本地路径。远程图片应先下载到本地并检查文件存在，再交给插件分享。

打开微信小程序

***Kit.launchMiniProgram({
  userName: 'gh_xxxxxxxx',
  path: 'pages/index/index?from=app',
  miniProgramType: 0,
  success(res) {
    console.log('打开小程序请求成功', res)
  },
  fail(err) {
    console.error('打开小程序失败', err)
  },
  complete(res) {
    console.log('打开小程序调用完成', res)
  }
})

userName 必须填写微信公众平台提供的 gh_ 开头小程序原始 ID，不是小程序 AppID。miniProgramType：0 正式版、1 开发版、2 体验版。

打开微信客服

***Kit.openCustomerService({
  corpId: '企业ID',
  url: 'https://work.weixin.qq.com/kfid/your-service-url',
  success(res) {
    console.log('打开微信客服请求成功', res)
  },
  fail(err) {
    console.error('打开微信客服失败', err)
  },
  complete(res) {
    console.log('打开微信客服调用完成', res)
  }
})

支付与商家转账

支付和转账参数必须来自业务服务端。以下占位值只说明字段结构，不能直接用于生产交易。

微信支付

***Kit.pay({
  partnerId: '服务端返回的商户号',
  prepayId: '服务端返回的预支付单号',
  nonceStr: '服务端返回的随机串',
  timeStamp: 1720000000,
  package: 'Sign=WXPay',
  sign: '服务端生成的支付签名',
  signType: 'MD5',
  success(res) {
    console.log('微信支付回调成功', res)
    // 最终支付状态仍应由服务端查询微信订单或接收支付通知确认。
  },
  fail(err) {
    console.error('微信支付失败', err)
  },
  complete(res) {
    console.log('微信支付流程完成', res)
  }
})

客户端成功回调不能代替服务端订单确认。发货、充值等业务必须以服务端验证后的支付结果为准。

商家转账用户确认

***Kit.requestMerchantTransfer({
  mchId: '服务端返回的商户号',
  package: '服务端返回的转账业务包参数',
  appId: 'wx1234567890abcdef',
  openId: '服务端确认的用户 openId',
  transferId: '服务端返回的转账单号',
  businessType: 'transfer_to_change',
  success(res) {
    console.log('已完成商家转账用户确认请求', res)
  },
  fail(err) {
    console.error('商家转账确认失败', err)
  },
  complete(res) {
    console.log('商家转账确认流程完成', res)
  }
})

高级能力

分享微信小程序卡片

***Kit.share({
  type: 4,
  scene: 0,
  title: '小程序卡片标题',
  desc: '小程序卡片说明',
  thumbImageUrl: '/storage/emulated/0/Download/mini-thumb.jpg',
  miniProgram: {
    userName: 'gh_xxxxxxxx',
    path: 'pages/index/index?from=share',
    miniProgramType: 0,
    webpageUrl: 'https://example.com/fallback'
  },
  success(res) {
    console.log('小程序卡片分享请求成功', res)
  },
  fail(err) {
    console.error('小程序卡片分享失败', err)
  },
  complete(res) {
    console.log('小程序卡片分享流程完成', res)
  }
})

监听微信回流

const launchListener = (res) => {
  console.log('收到微信回流数据', res)
}

***Kit.onLaunchFromWX({
  success: launchListener,
  fail(err) {
    console.error('订阅微信回流失败', err)
  },
  complete(res) {
    console.log('微信回流订阅调用完成', res)
  }
})

// 页面或业务模块销毁时解除监听。
***Kit.offLaunchFromWX(launchListener)

iOS 受 Swift 闭包比较限制，offLaunchFromWX(listener?) 会清空当前插件内的全部回流监听器；请按页面生命周期统一管理订阅。

使用兼容对象入口

如果旧业务习惯通过一个 SDK 对象调用能力，可以使用：

const sdk = ***Kit.getTT***SDK()

console.log('微信是否安装', sdk.isInstall())
sdk.openWXApp({
  success(res) {
    console.log('已提交拉起微信请求', res)
  },
  fail(err) {
    console.error('拉起微信失败', err)
  },
  complete(res) {
    console.log('兼容对象调用完成', res)
  }
})

新项目优先直接调用模块导出的统一 API；兼容对象不提供额外能力。

iOS 接入前必检

iOS 微信 OpenSDK 注册依赖宿主应用的签名、URL Scheme、Associated Domains 和 Universal Link。微信开放平台页面已经填写并不代表配置已经进入最终 IPA；建议在调用 register 前完成以下检查。

1. Universal Link 强制要求

• 必须使用 https://，不支持 http://。
• 必须以 / 结尾，例如 https://your.domain.com/app/。
• 代码传入的 universalLink 必须与微信开放平台 iOS 应用配置完全一致，包括协议、域名、路径、大小写和结尾 /。
• 域名必须能从公网正常访问；证书无效、重定向、鉴权页面、HTML 错误页或 4xx/5xx 都会导致校验失败。

2. AASA 在线检查

服务器应在以下标准地址之一提供 apple-app-site-association 文件，推荐同时支持两个地址：

https://your.domain.com/apple-app-site-association
https://your.domain.com/.well-known/apple-app-site-association

可以在打包前直接检查响应：

curl -i https://your.domain.com/apple-app-site-association
curl -i https://your.domain.com/.well-known/apple-app-site-association

有效响应应为 HTTP 200，不能跳转到其他地址或登录页。AASA 最小示例：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCDE12345.com.example.app",
        "paths": ["*"]
      }
    ]
  }
}

其中 ABCDE12345 替换为 Apple Team ID，com.example.app 替换为最终 IPA 的 Bundle ID。

paths 如何填写

paths 不是固定值，它用于限制该域名下哪些路径可以关联并唤起 App，必须覆盖实际使用的 Universal Link 路径。

例如 AASA 配置为 "paths": ["/ulink/*"] 时，微信开放平台、manifest.json 和 register 参数中的 Universal Link 都应使用 https://your.domain.com/ulink/，不能仍填写域名根路径。

3. IPA 必须包含的配置

• Bundle ID 与微信开放平台 iOS 应用配置一致。
• URL Scheme 包含微信移动应用 AppID，例如 wx1234567890abcdef。
• Associated Domains entitlement 包含对应域名，例如 applinks:your.domain.com，这里不要填写 https:// 或路径。
• Apple Developer 后台对应 App ID 已开启 Associated Domains，且打包使用的描述文件包含该能力。

uni-app 项目可在 HBuilderX 的 manifest.json 可视化界面中进入“App 常用其它设置 → iOS 设置 → 关联域（Associated Domains）”进行配置，也可以在源码视图的 app-plus.distribute.ios 节点中加入：

{
  "capabilities": {
    "entitlements": {
      "com.apple.developer.associated-domains": [
        "applinks:your.domain.com"
      ]
    }
  }
}

uni-app x 项目在 HBuilderX 4.71 及以上版本可使用 manifest.json 的 iOS 关联域可视化配置；如项目采用 iOS 原生资源配置，则在 nativeResources/ios/UniApp.entitlements 中写入同一个 com.apple.developer.associated-domains 数组。不要在 uni-app x 项目中照搬 uni-app 的 app-plus 节点。

微信 SDK 配置中的 UniversalLinks 和 Associated Domains 是两项不同配置，不能互相替代：

{
  "sdkConfigs": {
    "share": {
      "weixin": {
        "appid": "wx1234567890abcdef",
        "UniversalLinks": "https://your.domain.com/"
      }
    }
  }
}

• UniversalLinks 使用完整 HTTPS 地址，包含实际路径并以 / 结尾。
• Associated Domains 只填写 applinks:域名，不包含 https://、路径和结尾 /。
• 只在 sdkConfigs 中填写 UniversalLinks，不代表 Associated Domains 已进入最终 IPA 的签名权限。

更换域名后是否需要重新生成 Profile

Apple Developer 网站中的 Associated Domains 开关只表示 App ID 可以使用该能力，不保存具体 Universal Link 域名。因此，已经开启该能力且当前 Profile 已包含 Associated Domains 时，更换域名通常不需要关闭后重新开启，也不需要仅因域名变化重新生成 Profile。

以下情况需要重新生成 Profile：

• Associated Domains 是在当前 Profile 生成之后才首次开启的。
• 云打包提示 Profile 不支持 Associated Domains。
• 检查 Profile 后确认其中不包含 com.apple.developer.associated-domains。

Profile 允许 Associated Domains 仍不等于最终 IPA 已写入目标域名，最终应以 App 主程序的签名 entitlements 为准。

以上任一项发生变化后，都必须重新云打包，或重新制作并安装 iOS 自定义基座。资源热更新、WGT/appResource 更新不能改变 IPA 的 Info.plist、entitlement 或签名描述文件。

4. 9014108 排查顺序

当注册失败并返回 *** signature or config invalid 时，按以下顺序处理：

1. 用上方 curl 命令确认 AASA 当前返回 200，先解决超时、重定向或 502 等服务器问题。
2. 逐字符核对微信开放平台、代码 universalLink 和打包配置中的地址。
3. 核对微信 AppID、最终 Bundle ID、Apple Team ID 与 AASA appID。
4. 检查最终 IPA 的 URL Scheme、Associated Domains entitlement 和描述文件，不要只查看后台截图。
5. 删除旧应用，安装重新打包后的基座或正式包，再调用 register。

重新打包后，最终 IPA 的主程序签名中应能看到类似内容：

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:your.domain.com</string>
</array>

如果签名中没有该字段，即使 HBuilderX、微信开放平台和服务器截图看起来都已配置，微信 SDK 仍可能注册失败。重新打包时还应提升 iOS 构建号；构建号低于已安装、TestFlight 或 App Store 中的版本时，可能无法覆盖安装或上传。

Android 正常不代表 iOS 配置正确：Android 不使用 iOS Universal Link、AASA 和 Associated Domains。9014108 发生在 SDK 注册阶段时，后续登录、分享、支付或打开小程序都不会执行。

完整 API 参考

以下内容用于查询完整参数。第一次接入建议先完成前面的“五分钟最小接入”，再按业务场景查阅对应 API。

API 列表

• register(options)
• isInstall()
• isWXAppSupportApi(api)
• openWXApp(options)
• getApiSupportInfo(options)
• login(options)
• share(options)
• pay(options)
• requestMerchantTransfer(options)
• launchMiniProgram(options)
• openCustomerService(options)
• onLaunchFromWX(options)
• offLaunchFromWX(listener?)
• getTT***SDK()

register(options)

isInstall()

同步返回当前设备是否安装微信。

返回值：boolean。

isWXAppSupportApi(api)

返回值：boolean。

openWXApp(options)

getApiSupportInfo(options)

login(options)

share(options)

pay(options)

requestMerchantTransfer(options)

launchMiniProgram(options)

userName 必须填写微信公众平台提供的 gh_ 开头小程序原始 ID，不是小程序 AppID。

***Kit.launchMiniProgram({
  userName: 'gh_xxxxxxxx',
  path: 'pages/index/index',
  miniProgramType: 0,
  success(res) {
    console.log('打开小程序请求成功', res)
  },
  fail(err) {
    console.error('打开小程序失败', err)
  },
  complete(res) {
    console.log('打开小程序调用完成', res)
  }
})

openCustomerService(options)

onLaunchFromWX(options)

offLaunchFromWX(listener?)

取消微信回流事件监听。受 Swift 闭包不支持可靠相等比较的限制，iOS 传入或不传入 listener 都会清空当前全部微信回流监听器；其他平台仍按原有实现处理指定监听器。

getTT***SDK()

返回包含统一公开能力的兼容对象，适用于旧业务按 SDK 对象组织调用的场景。该方法不接收参数，也不会自动注册微信 SDK；仍需先调用返回对象的 register(options)。

返回值说明

错误码说明

权限说明

• Android：按微信 OpenSDK 要求完成应用与权限配置。
• iOS：需配置 URL Scheme 与 Universal Link。

自定义基座说明

本插件接入微信 OpenSDK（原生依赖与平台配置），默认需要自定义基座。

完整示例源码

• uni-app 综合调试页：uni_modules/lizhao-***-kit/example/uniapp/***Kit.vue
• uni-app x 接入示例：uni_modules/lizhao-***-kit/example/uniappx/index.uvue

综合调试页提供注册参数、安装检测、API 能力、登录、分享、支付、小程序、客服、回流监听和运行日志，适合在自定义基座中逐项验收。复制到业务页面时，只保留实际需要的能力和参数，不要把调试占位值带入生产环境。

目录结构

uni_modules/lizhao-***-kit
├─ package.json
├─ readme.md
├─ changelog.md
├─ example
│  ├─ uniapp
│  └─ uniappx
└─ utssdk
   ├─ interface.uts
   ├─ unierror.uts
   ├─ index.uts
   ├─ app-android
   ├─ app-ios
   ├─ app-harmony
   ├─ web
   ├─ mp-weixin
   └─ mp-alipay

常见问题

返回 9014102 *** sdk not registered

其他微信能力调用早于 register 成功回调。请把业务调用放到注册成功后的状态流程中，不要仅在页面加载时并行调用。

返回 9014104 *** not installed

当前设备未安装微信，或系统无法识别微信客户端。先使用 isInstall() 检查，并在安装了正式微信的真机复测。

iOS 返回 9014108，但 Android 正常

优先检查 Universal Link、AASA、URL Scheme、Bundle ID、Associated Domains 和描述文件。Android 不使用这些 iOS 配置，因此 Android 正常不能排除 iOS 宿主配置问题。

修改 Universal Link 后仍然报旧错误

Universal Link、entitlement、URL Scheme 和签名配置进入原生安装包，不能通过页面热更新或 WGT/appResource 更新。请重新云打包或制作 iOS 自定义基座，卸载旧应用后再安装测试。

回调日志出现 ReferenceError: Can't find variable

检查客户页面回调参数名是否一致。例如 fail(er) 内部必须读取 er，或统一写成 fail(err) 后读取 err。插件已经触发失败回调时，客户回调函数内部的变量错误会覆盖真正的 SDK 错误日志。

success 是否代表支付或分享业务最终成功

不同能力的成功语义不同。支付结果必须由服务端查询订单或接收微信通知确认；拉起小程序、客服或微信客户端的成功回调表示请求已成功提交，不代表用户完成了后续业务。

注意事项

1. 必须先调用 register，再调用其他微信能力。
2. pay 与 requestMerchantTransfer 的签名参数必须由服务端生成。
3. 不支持平台会返回明确错误，不会静默成功。
4. iOS 需确保开放平台配置与 universalLink 严格一致。

联系方式

信-微：l-z-1-8-7-1512-5421（-去掉，不这样写会被和谐）

作者系列 UTS 插件

以下为已在 DCloud 插件市场上架的作者系列 UTS 插件，可按业务场景组合使用。未列出的插件表示当前未确认公开市场页，后续上架后再补充。