更新记录

1.0.0（2026-04-13）

1.0.0

• 能力：在 App 内通过 UTS（Android / 鸿蒙）与 HTML5+（iOS）跳转微信、支付宝小程序；业务侧统一使用 unified-launcher 的 launchMiniProgram。
• 平台：Android、iOS（App-Plus）、HarmonyOS。
• 对外 API：仅 launchMiniProgram(options)（根路径为 UTS 绑定，iOS 生产请走 unified-launcher）。环境是否可用、当前系统等由业务侧通过 uni.getSystemInfoSync 等自行判断。
• 参数（LaunchOptions）：type（*** | alipay）、微信必填 userName / appId，支付宝必填 alipayAppId，path / miniProgramType 等见 index.d.ts 与 readme。
• 返回值：LaunchResult（success、code?、message?）；unified-launcher 统一为 Promise；底层 UTS 在 Android 多为同步对象、鸿蒙多为 Promise。
• 错误码：由 utssdk/unierror.uts 映射（1xxx 通用/参数、2xxx 未安装、3xxx SDK、4xxx 鸿蒙等），失败时附带中文 message。

平台兼容性

uni-app(4.87)

app-miniprogram-launcher

在 uni-app App 端（Android、iOS、HarmonyOS）拉起微信小程序、支付宝小程序的轻量工具插件；对外能力仅为 launchMiniProgram（见 unified-launcher）。

从宿主 App 跳转到小程序，依赖的是开放平台上的 「移动应用」 资质（与「小程序」后台不同）：须在 微信开放平台、支付宝开放平台 分别创建并完善 移动应用，填写包名、签名、Bundle ID、Universal Links 等与主工程一致的信息，并在主工程 manifest 中配置对应 SDK / AppID。详见 第 7 节。

文中 AppID、包名、域名 等均为占位符，接入时请替换为开放平台实际登记信息；勿将真实密钥、签名等材料提交到公开仓库。

目录

• 1. 快速接入步骤
• 2. 插件能力一览
• 3. 工作原理与调用链
• 4. 目录结构说明
• 5. 推荐用法：unified-launcher
• 6. 仅使用 UTS 原生接口（可选）
• 7. 开放平台与 manifest 配置（含 7.0 移动应用注册说明）
• 8. API 说明
• 9. 错误码与排查
• 10. 示例页面
• 11. 用户从小程序回到 App
• 12. 常见问题（FAQ）
• 13. 许可证

1. 快速接入步骤

1. 将插件目录 uni_modules/app-miniprogram-launcher 放入工程（与 uni-app uni_modules 规范一致）。
2. 在 微信开放平台、支付宝开放平台 分别完成 移动应用 注册及平台要求的各项配置（包名、签名、iOS 能力、与小程序/应用的关联等），取得调用所需的 移动应用 AppID 等；仅拥有小程序账号不足以完成从 App 侧拉起，详见第 7 节。
3. 在 manifest / manifest.config.ts 中按平台配置微信 SDK、支付宝相关能力与开放平台登记信息对齐（iOS 需配置 Universal Links 等）。
4. 业务代码通过 统一入口 调用，无需自行拆分 iOS 与 Android / 鸿蒙两套 API：

import { launchMiniProgram } from '@/uni_modules/app-miniprogram-launcher/unified-launcher'

5. 调起时用 await launchMiniProgram({ ... })（内部已处理同步 / 异步差异，见第 5 节）。

2. 插件能力一览

说明：

• 使用本插件前须完成 微信 / 支付宝开放平台「移动应用」 注册及 manifest 配置，见 7.0。
• iOS 上微信要求宿主 App 在 manifest 里集成 微信 SDK（share） 并配置 Universal Links，否则 plus.share 可能拿不到微信服务。
• 支付宝 在 Android / 鸿蒙 / iOS 上均依赖用户设备安装 支付宝客户端，通过 alipays://platformapi/startapp?... 把参数交给支付宝 App。
• utssdk/app-ios/index.uts 不参与真实跳转，仅为满足 UTS 插件在 iOS 工程编译 的占位；真实 iOS 逻辑在 launch-app-plus.ts，由 unified-launcher.ts 自动选用。

3. 工作原理与调用链

整体为两层封装：

业务页面 / 业务模块
        ↓
unified-launcher.ts  ← 按运行环境选择实现
        ↓
   ┌────┴────┐
   ↓         ↓
iOS         Android / HarmonyOS
launch-     UTS 原生（微信 SDK / 系统打开 alipays）
app-plus.ts
(HTML5+ / plus)

• 对接 unified-launcher 即可完成三端统一调用，无需在业务层手写平台分支。
• 若仅从 @/uni_modules/app-miniprogram-launcher 根路径导入，对应为 UTS 绑定；在 iOS 工程中为占位实现，无法完成真实拉起，生产环境 iOS 应使用 unified-launcher。

4. 目录结构说明

app-miniprogram-launcher/
├── index.d.ts                    # TypeScript 类型与 UTS 导出声明（根 import 指向原生层）
├── unified-launcher.ts           # 三端统一入口（建议业务侧从此处 import）
├── launch-app-plus.ts            # iOS（App-Plus）HTML5+ 实现
├── package.json
├── readme.md
└── utssdk/
    ├── interface.uts               # UTS 侧参数 / 结果类型
    ├── unierror.uts                # 错误码与文案
    ├── example.vue                       # 示例页（需复制到业务 pages 并注册路由）
    ├── app-android/
    │   ├── config.json             # minSdk、微信 Maven 依赖等
    │   └── index.uts
    ├── app-harmony/
    │   ├── config.json             # @tencent/***_open_sdk 等
    │   └── index.uts
    └── app-ios/
        ├── config.json
        └── index.uts               # 编译占位，运行时不用

5. 推荐用法：unified-launcher

5.1 返回值与 Promise

• Android：UTS 层 launchMiniProgram 多为 同步 返回结果对象。
• 鸿蒙：UTS 层多为 Promise。
• iOS：launch-app-plus 内以回调封装为 Promise。

建议写法：

const result = await launchMiniProgram(options)

若调用链上仍存在「同步或 Promise 混用」的旧接口，可使用：

const result = await Promise.resolve(launchMiniProgram(options))

unified-launcher 导出的 launchMiniProgram 始终为 Promise<LaunchResult>，可直接 await。

5.2 调用示例（微信）

以下 ID 为 占位符，请替换为开放平台实际配置：

import { launchMiniProgram } from '@/uni_modules/app-miniprogram-launcher/unified-launcher'

async function open***Mini() {
  const result = await launchMiniProgram({
    type: '***',
    userName: 'gh_XXXXXXXXXXXX',        // 小程序「原始 ID」，在微信公众平台查看
    appId: 'wxXXXXXXXXXXXXXXXX',        // 微信开放平台「移动应用」AppID（不是小程序 AppID）
    path: 'pages/index/index?foo=1',    // 小程序页面路径，可与后端约定
    miniProgramType: 0,                 // 0 正式版 / 1 开发版 / 2 体验版
  })

  if (result.success) {
    uni.showToast({ title: '已发起跳转', icon: 'success' })
  } else {
    uni.showToast({ title: result.message ?? '失败', icon: 'none' })
  }
}

5.3 调用示例（支付宝）

const result = await launchMiniProgram({
  type: 'alipay',
  alipayAppId: '202100XXXXXXXXXX',      // 支付宝开放平台应用 ID
  path: 'pages/home/index',             // 复杂 path 可与支付模块一样带 query、编码参数
})

6. 仅使用 UTS 原生接口（可选）

适用于：只打 Android / 鸿蒙包，且希望少一层封装时。

import { launchMiniProgram } from '@/uni_modules/app-miniprogram-launcher'

注意：不要在 iOS App 上依赖该路径完成生产跳转，应改用第 5 节的 unified-launcher。

7. 开放平台与 manifest 配置

7.0 为什么必须注册「移动应用」？

因此：

1. 微信：在 微信开放平台 创建 移动应用（不是「小程序」菜单），将 Android 包名与签名、iOS Bundle ID 与 Universal Links、鸿蒙包名与签名（若适用）按指引填写并通过审核；代码里传入的 appId 须为该 移动应用的 AppID（wx 开头），userName 为要打开的 小程序原始 ID。主工程 manifest 中微信 SDK（如 share.weixin）所填 appid 也应与此 移动应用 一致。
2. 支付宝：在 支付宝开放平台 创建 移动应用，完成平台要求的应用信息、与 小程序 / 跳转 相关的绑定或白名单（以当前支付宝文档为准）；代码里 alipayAppId 等为开放平台为该 移动应用 或关联能力下发的标识。主工程若对 Scheme、URL 白名单有要求，需与开放平台配置一致。
3. manifest：上述开放平台中的登记信息，必须在 manifest / manifest.config.ts 中逐项对齐（微信 Universal Links、鸿蒙 bundleName 与模块配置等），否则会出现 未集成 SDK、签名校验失败、无法调起 等问题。

插件只负责按参数发起跳转；不具备替代开放平台注册与 manifest 配置的效力。

7.1 开放平台准备项（速查）

7.2 Android（UTS）

• 依赖见 utssdk/app-android/config.json（含微信 Android SDK 等），一般无需改包名在插件里，包名与签名以主工程为准。
• 调用微信时 appId 在 JS 里传入 即可（与开放平台「移动应用」一致）。
• 支付宝依赖用户安装官方支付宝 App；插件用 alipays:// 调起。

7.3 HarmonyOS（UTS）

• 依赖见 utssdk/app-harmony/config.json（如 @tencent/***_open_sdk）。
• 主工程 manifest.config.ts 的 app-harmony 中需配置微信 appid、bundleName 等与开放平台一致（键名以当前 uni-app 模板为准）。

7.4 iOS（App-Plus + manifest）

iOS 必须在主工程 manifest 中配置微信模块，示例结构如下（数值均为占位）：

// manifest.config.ts 片段示例 — 请按主工程实际结构调整
export default defineManifestConfig({
  'app-plus': {
    distribute: {
      sdkConfigs: {
        share: {
          weixin: {
            appid: 'wxXXXXXXXXXXXXXXXX',
            UniversalLinks: 'https://your-domain.example/universal-link-prefix/',
          },
        },
      },
    },
  },
})

同时需在 https://your-domain.example 上托管 apple-app-site-association（具体格式见 苹果文档），且与开放平台填写的 Universal Links 一致。

7.5 配置检查清单

• [ ] 微信：各端包名 / Bundle ID / 签名与开放平台登记一致
• [ ] iOS：Universal Links 可访问，且与微信开放平台配置一致
• [ ] 真机已安装 微信、支付宝客户端
• [ ] 业务侧使用 unified-launcher；iOS 未单独依赖根路径 UTS 作为生产跳转

8. API 说明

类型定义见根目录 index.d.ts。常用字段：

launchMiniProgram(options)（unified-launcher 导出）

返回值： Promise<LaunchResult>，LaunchResult 含 success、code?、message?。以 success 为准判断成功与否；鸿蒙 UTS 成功时可能带 code: 200。非 App 环境会得到 success: false（如 code: 1004）。是否需要跳转、当前运行平台等请用业务侧 uni.getSystemInfoSync 等自行判断。

9. 错误码与排查

9.1 常见 code（与 message 对照）

9.2 排查思路

1. 先看 result.message：插件内已对常见错误做了中文说明，可直接 Toast。
2. iOS 微信 3001：检查 manifest 的 share.weixin、Universal Links、是否在真机调试。
3. 支付宝 2003：确认已安装支付宝；alipayAppId 与 path 是否与开放平台一致。
4. 鸿蒙 400x：确认在 UIAbility 生命周期内 调用；依赖版本 ≥ 官方要求。

10. 示例页面

路径：utssdk/example.vue

• 复制到业务 pages 目录，并在 pages.json / pages.config.ts 中注册路由。
• 示例页从 unified-launcher 引用，与生产环境推荐写法一致。
• 将页面内 gh_ / wx / 202100 等占位 ID 替换为实际值后再联调。

11. 用户从小程序回到 App

插件 不负责 把微信原生回调直接转成 JS 事件。若需在小程序里点「返回 App」并带参数，需要：

1. 小程序端使用官方 launchApp 等能力；
2. Android 在原生 WXEntryActivity（或项目封装层）里取扩展字段，再通过 uni.$emit 等方式通知 JS；
3. iOS 在微信 SDK 回调里同理转发。

具体实现与工程打包、原生封装方式相关，需在 宿主 App 侧补充。

12. 常见问题（FAQ）

Q：为何推荐使用 unified-launcher 而非插件根路径？
A：根路径为 UTS 导出。iOS 侧 UTS 为 编译占位，无法完成真实拉起；unified-launcher 在 iOS 上会走 launch-app-plus.ts（HTML5+）。

Q：可以把 alipayAppId 和 userName 都传吗？
A：可以。支付宝链路主要使用 alipayAppId 与 path。

Q：H5 / 小程序里能调这个吗？
A：不能。unified-launcher 在非 App 环境会返回 不支持 的 LaunchResult。请在对应平台使用各平台自己的打开小程序方式。

13. 许可证

MIT License