更新记录

1.2.0（2026-09-02） 下载此版本

• HarmonyOS 新增小程序回跳监听，覆盖冷启动与 onNewWant 场景。
• 新增 onMiniProgramReturn / offMiniProgramReturn，返回小程序 app-parameter 原始值。

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

launchMiniProgram(options)：带参打开指定小程序页面 isWeChatInstalled()：检查微信是否安装 支持正式版、开发版和体验版 统一错误码及 success/fail/complete Android OpenSDK 6.8.34 iOS OpenSDK 2.0.7

平台兼容性

uni-app x(5.25)

微信小程序跳转（Android/iOS/HarmonyOS，免费开源）

一个面向 uni-app x App 端的免费 UTS API 插件。它调用微信 OpenSDK，从 App 直接打开指定微信小程序页面，并通过 path 携带参数。

• Android、iOS 与 HarmonyOS 使用同一套 API
• 支持正式版、开发版、体验版小程序
• Android 依赖微信 OpenSDK 6.8.34
• iOS 依赖微信 OpenSDK 2.0.7
• HarmonyOS 依赖微信 OpenSDK 1.0.15
• HarmonyOS 支持接收小程序 button open-type="launchApp" 的 app-parameter
• 不联网、不采集数据、无广告、MIT 许可证

使用前准备

1. 在微信开放平台创建移动应用并取得移动应用 AppID。
2. 将 Android 应用包名和签名、iOS Bundle ID 与 Universal Link 配置到该移动应用。
3. 将目标小程序与该移动应用绑定。
4. 涉及三方原生 SDK，真机调试时请制作自定义基座。

Android 如需从小程序使用 button open-type="launchApp" 返回宿主 App，请在 manifest.json 中启用微信 uni-share 模块。插件会复用 HBuilderX uni-weixin-common 提供的 ${applicationId}.wxapi.WXEntryActivity，不重复声明微信回调入口。修改原生模块配置后必须 重新制作自定义基座或正式安装包，仅更新前端资源不会改变回跳入口。

iOS 还需要在宿主 App 中完成以下微信 OpenSDK 标准配置：

• 将移动应用 AppID 加入 URL Types / URL Schemes。
• 配置 Associated Domains，对应微信开放平台登记的 Universal Link。
• 调用时传入同一个 universalLink。

插件已加入微信查询 Scheme：weixin、weixinULAPI、weixinURLParamsAPI。

基本用法

import {
  launchMiniProgram,
  isWeChatInstalled,
  LaunchMiniProgramOptions
} from '@/uni_modules/ling-launcher'

const ticket = '后端签发的一次性短时票据'

const options : LaunchMiniProgramOptions = {
  appId: 'wx1234567890abcdef',
  userName: 'gh_xxxxxxxxxxxx',
  path: 'pages/pay/index?ticket=' + encodeURIComponent(ticket),
  miniProgramType: 0,
  // Android 会忽略此字段；iOS 必填。
  universalLink: 'https://example.com/app/',
  success: (res) => {
    console.log('微信已接收跳转请求', res.errMsg)
  },
  fail: (err) => {
    console.error('跳转失败', err.errCode, err.errMsg)
  }
}

if (isWeChatInstalled(options.appId)) {
  launchMiniProgram(options)
} else {
  uni.showToast({ title: '请先安装微信', icon: 'none' })
}

userName 是小程序原始 ID（gh_...），不是小程序 AppID。

HarmonyOS 接收小程序返回参数

在 App 启动时注册一次监听。插件会同时接收 EntryAbility 冷启动的 onCreate 和后台回跳的 onNewWant，并使用微信 OpenSDK 解析 Want：

import {
  MiniProgramReturnResult,
  onMiniProgramReturn,
  offMiniProgramReturn
} from '@/uni_modules/ling-launcher'

onMiniProgramReturn('wx1234567890abcdef', (result : MiniProgramReturnResult) => {
  console.log('小程序返回参数', result.appParameter)
})

// 不再需要监听时调用
offMiniProgramReturn()

小程序侧通过 button 返回并传值：

<button open-type="launchApp" app-parameter='{"action":"payment_success"}'>
  返回 App
</button>

回跳参数只表示小程序主动返回时携带的业务提示，支付状态、订单状态等仍必须向服务端查询确认。

带参规则

参数直接放在 path 的 query 中：

path: 'pages/order/detail?ticket=' + encodeURIComponent(ticket)

小程序侧在目标页面的 onLoad 中读取：

onLoad((query) => {
  const ticket = query['ticket'] ?? ''
})

不要把支付金额、用户身份、权限结论、长期 token 或其他敏感数据直接放进 query。推荐仅传后端签发的短时、一次性、绑定业务场景的票据；小程序拿票据向后端换取真实业务数据。

参数

错误码

success 只代表微信 OpenSDK 接收了跳转请求，不代表小程序页面加载成功，更不代表小程序中的支付或业务已完成。业务结果应由小程序和后端共同确认。

常见问题

为什么提示注册失败或没有拉起微信？

优先检查微信开放平台中的 Android 包名/签名、iOS Bundle ID/Universal Link 是否与当前安装包完全一致。调试包和正式包签名不同也会导致失败。

为什么修改代码后标准基座无效？

本插件集成了微信三方原生 SDK，需要自定义基座或正式云打包。

可以用于支付吗？

插件只负责打开小程序。支付应由小程序使用自己的合法支付能力发起；App 端不要相信 query 中的金额或支付结果，最终状态以服务端支付回调和查单结果为准。

开源协议

MIT。欢迎免费使用、修改和二次发布，也欢迎把修复反馈给社区。

参考资料

• DCloud：UTS 插件开发
• DCloud：UTS 插件使用 CocoaPods
• 微信开放平台：移动应用拉起小程序