更新记录

1.4.2（2026-09-08）

• 修复蒸汽模式下安卓编译报错。
• 修复 Android 云打包将多个 uts 合并进 index.kt 后，launchMiniProgram / openCustomerServiceChat 同名声明冲突导致编译失败。
• manifest.json增加安卓、ios权限等配置示例。

1.4.1（2026-09-08）

• 修复 Android 蒸汽模式下 isWXAppInstalled 等 API 因再导出无法进入 uts-proxy 导致编译失败。

1.4.0（2026-09-08）

• 新增打开微信客服 openCustomerServiceChat，支持鸿蒙、Android、iOS、微信小程序。
• API 支持摇树：按接口拆分实现文件，未引用的 API 不会打入包内。

平台兼容性

uni-app(4.83)

uni-app x(4.83)

打开微信小程序 / 微信客服

基于微信 Open SDK / 微信小程序官方接口封装的 UTS 插件，一套 API 支持 HarmonyOS / Android / iOS / 微信小程序 打开微信小程序、打开微信客服，无需条件编译。

App 端与微信小程序端的 appId 含义不同，请按平台填写：

• App（鸿蒙 / Android / iOS）：appId 为微信开放平台移动应用 AppID；userName 为小程序原始 ID（gh_ 开头）。
• 微信小程序：appId 为要打开的目标小程序 AppID（wx 开头）；无需 userName。

示例工程

本仓库即示例工程（uni-app x）。导入插件后可直接对照：

鸿蒙权限与跳转查询 不要只改插件内的 utssdk/app-harmony/module.json5。querySchemes 只能写在宿主 entry 模块，完整写法以示例工程 harmony-configs 为准，见下文 HarmonyOS。

接入前准备

App 端

1. 在微信开放平台创建移动应用，获取 AppID（不要填小程序 AppID）。
2. 分别填写并审核通过各端信息：Android 包名与签名、iOS Bundle ID 与 Universal Links、鸿蒙 Bundle ID 与 Identifier。
3. 准备目标小程序的原始 ID（以 gh_ 开头）。
4. 真机已安装微信。模拟器通常无法拉起。
5. Android、iOS 需制作自定义基座，运行时选择自定义基座，标准基座无法加载微信 Open SDK。
6. 鸿蒙在 HBuilderX 中「运行到鸿蒙 / 发行 App-Harmony」，并把示例工程 harmony-configs 中的微信相关配置合并到宿主工程。
7. 打开微信客服还需：开放平台账号已认证；移动应用审核通过（未上架每天最多拉起 100 次）；前往微信客服官网绑定移动应用 AppID 与企业 ID（一个 AppID 最多绑定 15 个企业 ID）。Android OpenSDK ≥ 6.7.9，iOS OpenSDK ≥ 1.9.2，鸿蒙微信 ≥ 1.0.11 且 OpenSDK ≥ 1.0.15。

微信小程序端

1. 准备目标小程序的 AppID（wx 开头，不是 gh_ 原始 ID）。
2. 登录微信公众平台 → 设置 → 第三方设置 → 小程序跳转，添加允许跳转的目标小程序 AppID。
3. 跳转必须由用户点击触发，不能在 onLoad 等生命周期里自动调用。
4. 跳转前微信会弹出确认框；用户取消时走 fail，errMsg 含 cancel。
5. 开发者工具只会校验调用是否成功，不会真实跳转，请用真机预览验证。
6. miniprogramType / envVersion 仅在当前小程序为开发版或体验版时生效；当前是正式版时，只能打开正式版。
7. 打开微信客服：在微信公众平台 → 功能 → 客服 → 微信客服 绑定同主体企业 ID；客服链接从微信客服管理后台获取。基础库需 ≥ 2.19.0。

调用

从 @/uni_modules/omn-weixin-openmp 导入即可，各端 API 一致。请按需具名导入，未使用的 API 会被摇树剔除：

import { launchMiniProgram, openCustomerServiceChat, isWXAppInstalled, LaunchMiniProgramOptions, OpenCustomerServiceChatOptions } from '@/uni_modules/omn-weixin-openmp'

完整可运行页面见示例工程 pages/index/index.uvue。

鸿蒙 / 微信小程序已开启 API 摇树：launchMiniProgram、openCustomerServiceChat、isWXAppInstalled 分文件实现。只导入需要的方法即可，不要使用 import *。Android 蒸汽模式与 iOS 云编译的 uts-proxy 无法识别再导出，且云打包会按文件名生成同名声明，因此 Android / iOS 使用单文件 index.uts 导出，暂不摇树。

Vue 3（uni-app x）

<template>
    <view class="page">
        <text class="title">打开微信小程序</text>
        <text class="hint">App 端通过微信 Open SDK 拉起；微信小程序端通过 uni.navigateToMiniProgram 跳转。请按平台填写 appId。</text>

        <view class="form">
            <text class="label">移动应用 AppID</text>
            <input class="input" v-model="appId" placeholder="微信开放平台移动应用 AppID" />

            <text class="label">小程序原始 ID</text>
            <input class="input" v-model="userName" placeholder="gh_ 开头，不是小程序 AppID" />

            <text class="label">页面路径（可选）</text>
            <input class="input" v-model="path" placeholder="pages/index/index" />

            <text class="label">Universal Link（iOS）</text>
            <input class="input" v-model="universalLink" placeholder="https://your.domain.com/app/" />

            <text class="label">小程序版本</text>
            <view class="type-row">
                <text class="type-item" :class="miniprogramType == 0 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(0)">正式版</text>
                <text class="type-item" :class="miniprogramType == 1 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(1)">开发版</text>
                <text class="type-item" :class="miniprogramType == 2 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(2)">体验版</text>
            </view>
        </view>

        <button class="btn" type="primary" @click="onCheckInstalled">检测微信是否安装</button>
        <button class="btn" type="primary" @click="onLaunchMiniProgram">打开微信小程序</button>

        <text class="label">企业 ID</text>
        <input class="input" v-model="corpId" placeholder="企业微信 CorpID" />
        <text class="label">客服链接</text>
        <input class="input" v-model="kfUrl" placeholder="https://work.weixin.qq.com/kfid/kfcxxxxx" />
        <button class="btn" type="primary" @click="onOpenCustomerServiceChat">打开微信客服</button>
        <text class="result">{{ resultText }}</text>
    </view>
</template>

<script setup lang="uts">
    import { launchMiniProgram, openCustomerServiceChat, isWXAppInstalled, LaunchMiniProgramOptions, OpenCustomerServiceChatOptions } from '@/uni_modules/omn-weixin-openmp'

    const appId = ref('wxYourAppId')
    const userName = ref('gh_xxxxxx')
    const path = ref('pages/index/index')
    const universalLink = ref('')
    const miniprogramType = ref(0)
    const corpId = ref('')
    const kfUrl = ref('')
    const resultText = ref('')

    function setMiniProgramType(type : number) {
        miniprogramType.value = type
    }

    function onCheckInstalled() {
        const installed = isWXAppInstalled(appId.value)
        resultText.value = installed ? '已安装微信' : '未安装微信，或 AppID 为空'
        uni.showToast({
            title: resultText.value,
            icon: 'none'
        })
    }

    function onLaunchMiniProgram() {
        const type = miniprogramType.value
        const options : LaunchMiniProgramOptions = {
            appId: appId.value,
            userName: userName.value,
            path: path.value,
            miniprogramType: type,
            universalLink: universalLink.value,
            success: (_res) => {
                resultText.value = '已发起拉起'
                uni.showToast({
                    title: '已发起拉起',
                    icon: 'success'
                })
            },
            fail: (err) => {
                resultText.value = err.errCode.toString() + ' ' + err.errMsg
                uni.showToast({
                    title: err.errMsg,
                    icon: 'none'
                })
            }
        }
        launchMiniProgram(options)
    }

    function onOpenCustomerServiceChat() {
        const options : OpenCustomerServiceChatOptions = {
            appId: appId.value,
            corpId: corpId.value,
            url: kfUrl.value,
            universalLink: universalLink.value,
            success: (_res) => {
                resultText.value = '已发起打开微信客服'
            },
            fail: (err) => {
                resultText.value = err.errCode.toString() + ' ' + err.errMsg
            }
        }
        openCustomerServiceChat(options)
    }
</script>

Vue 2

<template>
    <view class="page">
        <text class="title">打开微信小程序</text>
        <text class="hint">App 端通过微信 Open SDK 拉起；微信小程序端通过 uni.navigateToMiniProgram 跳转。请按平台填写 appId。</text>

        <view class="form">
            <text class="label">移动应用 AppID</text>
            <input class="input" v-model="appId" placeholder="微信开放平台移动应用 AppID" />

            <text class="label">小程序原始 ID</text>
            <input class="input" v-model="userName" placeholder="gh_ 开头，不是小程序 AppID" />

            <text class="label">页面路径（可选）</text>
            <input class="input" v-model="path" placeholder="pages/index/index" />

            <text class="label">Universal Link（iOS）</text>
            <input class="input" v-model="universalLink" placeholder="https://your.domain.com/app/" />

            <text class="label">小程序版本</text>
            <view class="type-row">
                <text class="type-item" :class="miniprogramType == 0 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(0)">正式版</text>
                <text class="type-item" :class="miniprogramType == 1 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(1)">开发版</text>
                <text class="type-item" :class="miniprogramType == 2 ? 'type-item-active' : ''"
                    @click="setMiniProgramType(2)">体验版</text>
            </view>
        </view>

        <button class="btn" type="primary" @click="onCheckInstalled">检测微信是否安装</button>
        <button class="btn" type="primary" @click="onLaunchMiniProgram">打开微信小程序</button>

        <text class="label">企业 ID</text>
        <input class="input" v-model="corpId" placeholder="企业微信 CorpID" />
        <text class="label">客服链接</text>
        <input class="input" v-model="kfUrl" placeholder="https://work.weixin.qq.com/kfid/kfcxxxxx" />
        <button class="btn" type="primary" @click="onOpenCustomerServiceChat">打开微信客服</button>
        <text class="result">{{ resultText }}</text>
    </view>
</template>

<script>
    import { launchMiniProgram, openCustomerServiceChat, isWXAppInstalled } from '@/uni_modules/omn-weixin-openmp'

    export default {
        data() {
            return {
                appId: 'wxYourAppId',
                userName: 'gh_xxxxxx',
                path: 'pages/index/index',
                universalLink: '',
                miniprogramType: 0,
                corpId: '',
                kfUrl: '',
                resultText: ''
            }
        },
        methods: {
            setMiniProgramType(type) {
                this.miniprogramType = type
            },
            onCheckInstalled() {
                const installed = isWXAppInstalled(this.appId)
                this.resultText = installed ? '已安装微信' : '未安装微信，或 AppID 为空'
                uni.showToast({
                    title: this.resultText,
                    icon: 'none'
                })
            },
            onLaunchMiniProgram() {
                launchMiniProgram({
                    appId: this.appId,
                    userName: this.userName,
                    path: this.path,
                    miniprogramType: this.miniprogramType,
                    universalLink: this.universalLink,
                    success: () => {
                        this.resultText = '已发起拉起'
                        uni.showToast({
                            title: '已发起拉起',
                            icon: 'success'
                        })
                    },
                    fail: (err) => {
                        this.resultText = err.errCode + ' ' + err.errMsg
                        uni.showToast({
                            title: err.errMsg,
                            icon: 'none'
                        })
                    }
                })
            },
            onOpenCustomerServiceChat() {
                openCustomerServiceChat({
                    appId: this.appId,
                    corpId: this.corpId,
                    url: this.kfUrl,
                    universalLink: this.universalLink,
                    success: () => {
                        this.resultText = '已发起打开微信客服'
                    },
                    fail: (err) => {
                        this.resultText = err.errCode + ' ' + err.errMsg
                    }
                })
            }
        }
    }
</script>

launchMiniProgram

openCustomerServiceChat

对应微信官方能力：

• App：App 拉起微信客服
• 微信小程序：wx.openCustomerServiceChat

import { openCustomerServiceChat } from '@/uni_modules/omn-weixin-openmp'

openCustomerServiceChat({
    appId: 'wxYourAppId', // App 端必填；微信小程序端可省略
    corpId: 'wwxxxxxxxx',
    url: 'https://work.weixin.qq.com/kfid/kfcxxxxx',
    success: () => {
        console.log('已发起打开微信客服')
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

isWXAppInstalled

const installed = isWXAppInstalled(appId)

• App：通过微信 Open SDK 检测是否安装微信。鸿蒙依赖宿主 querySchemes 含 weixin，否则会检测失败。
• 微信小程序：当前已运行在微信内，始终返回 true。

微信小程序调用示例

import { launchMiniProgram } from '@/uni_modules/omn-weixin-openmp'

launchMiniProgram({
    appId: 'wxTargetMiniProgramAppId', // 目标小程序 AppID，不是 gh_ 原始 ID
    path: 'pages/index/index?id=123',
    miniprogramType: 0,
    extraData: {
        from: 'omn-weixin-openmp'
    },
    success: () => {
        console.log('已发起跳转')
    },
    fail: (err) => {
        console.log(err.errCode, err.errMsg)
    }
})

错误码

各端配置

HarmonyOS

插件 HAR 已配置：

• 依赖 @tencent/wechat_open_sdk（utssdk/app-harmony/config.json）
• ohos.permission.INTERNET（utssdk/app-harmony/module.json5）

宿主工程还必须配置 entry 模块。 querySchemes 只能写在 entry，写在插件 HAR 里不生效。HBuilderX 运行 / 发行鸿蒙时，会把项目根目录 harmony-configs 整文件覆盖到产物工程，因此该文件必须是完整的 module.json5，不能只放 querySchemes。

按示例工程配置

本示例工程已给出可运行配置，请以该文件为准：

harmony-configs/entry/src/main/module.json5

接入宿主工程时任选其一：

1. 推荐：把上述文件复制到宿主工程相同路径（harmony-configs/entry/src/main/module.json5）。
2. 宿主已有该文件：打开示例文件，把其中与微信相关的字段合并进去（见下方）。
3. 宿主还没有 harmony-configs：先「运行到鸿蒙」一次，HBuilderX 会生成该目录；再按示例工程合并微信相关字段。官方说明见 鸿蒙的运行和发行。

示例工程中与微信相关、必须保留的字段如下（完整结构、abilities 等以 harmony-configs 文件为准，不要用残缺片段覆盖）：

{
  "module": {
    "abilities": [
      {
        "skills": [
          {
            "entities": ["entity.system.home"],
            "actions": [
              "action.system.home",
              "wxentity.action.open"
            ]
          }
        ]
      }
    ],
    "requestPermissions": [
      {
        "name": "ohos.permission.INTERNET"
      }
    ],
    "querySchemes": [
      "weixin",
      "wxopensdk"
    ]
  }
}

字段说明：

请保证打包签名的 Bundle ID、Identifier 与微信开放平台填写的一致。模拟器通常无法拉起微信，请用真机验证。

Android

插件已配置（utssdk/app-android/）：

• Maven 依赖 wechat-sdk-android:6.8.0
• AndroidManifest.xml：INTERNET、ACCESS_NETWORK_STATE
• Android 11+ 可见性 <queries><package android:name="com.tencent.mm" /></queries>
• 混淆保留规则 proguard-rules.pro

请保证打包签名与微信开放平台填写的一致。仅拉起小程序不需要 WXEntryActivity；若还要接收小程序回跳参数，需自行按微信文档增加 wxapi.WXEntryActivity。

iOS

插件已通过 CocoaPods 引入 WechatOpenSDK-XCFramework 2.0.5，并合并 LSApplicationQueriesSchemes：weixin、weixinULAPI、weixinURLParamsAPI。

宿主工程还需（示例已写在 manifest.json 的 app-ios）：

1. URL Types 中增加微信移动应用 AppID（与开放平台一致）。
2. 开启 Associated Domains，配置 Universal Links（applinks:域名，开放平台 paths 需带 /*），调用插件时传入完整 universalLink。
3. 把 your.domain.com 换成开放平台真实 UL 主机名；苹果后台该 App ID 须勾选 Associated Domains。
4. SDK 2.0.4+ 才能在 iOS 18 / Xcode 16 上稳定拉起微信。
5. 不要开启官方 uni-share 微信模块，以免与本插件 OpenSDK 重复集成。

仅拉起小程序时可不实现 WXApiDelegate；若要接收小程序返回 App 的数据，需按微信文档处理 Universal Link / URL。

微信小程序

打开另一个小程序时，插件内部调用 uni.navigateToMiniProgram，对应微信 wx.navigateToMiniProgram。

打开微信客服时，插件内部调用 uni.openCustomerServiceChat，对应微信 wx.openCustomerServiceChat。

1. 跳转其他小程序：在微信公众平台配置可跳转的小程序名单（设置 → 第三方设置 → 小程序跳转）。
2. 打开微信客服：在 功能 → 客服 → 微信客服 绑定同主体企业 ID；客服链接从微信客服后台复制。
3. 低版本基础库若仍读取 app.json 的 navigateToMiniProgramAppIdList，可在宿主工程 manifest.json 中补充：

{
    "mp-weixin": {
        "appid": "wxYourCurrentMiniProgramAppId",
        "navigateToMiniProgramAppIdList": [
            "wxTargetMiniProgramAppId"
        ]
    }
}

4. isWXAppInstalled 在微信小程序端始终返回 true（当前已运行在微信内）。

常见失败原因

• App 端 AppID 填成了小程序 AppID，或小程序端填成了 gh_ 原始 ID / 移动应用 AppID
• 开放平台对应端信息未审核通过
• 鸿蒙未把示例工程 harmony-configs 中的 querySchemes / INTERNET 配到宿主 entry（检测微信或拉起失败）
• Android 签名或包名不一致
• iOS 未配置 Universal Links / URL Scheme
• 未安装微信，或在模拟器上测试
• 微信小程序未在公众平台配置「小程序跳转」名单
• 微信小程序未由用户点击触发，或用户在确认弹窗中点了取消
• 当前小程序是正式版，却尝试打开开发版 / 体验版
• 打开微信客服时未绑定企业 ID（小程序后台「微信客服」或 App 端微信客服后台绑定 AppID）
• 客服链接过期 / 变更导致 bad_deeplink，需重新从微信客服后台复制链接
• 微信版本过低，不支持打开客服（Android 报 9010008）
• 使用加密版插件在鸿蒙端编译（请改用源码授权版）