更新记录
1.0.0(2026-11-20)
- 首个版本:企业微信 SSO 登录 UTS 插件,支持 Android / iOS / 鸿蒙三端。
- 提供
wxWorkInit(schema)注册应用、wxWorkLogin(options)发起授权两个 API。 - 成功回调返回授权
code(msg)与透传state,交由业务后端换取登录态。 - 统一错误码体系 9010001-9010008,中文错误提示附带原始原因。
- 回调保证
success/fail互斥且仅触发一次,complete仅触发一次。 - 内置腾讯企业微信开放 SDK:Android AAR、iOS 静态库、鸿蒙 har(@tencent/wecom_open_sdk)。
- Android 内置 queries 企业微信包名;iOS 内置 LSApplicationQueriesSchemes;鸿蒙需配置 querySchemes。
平台兼容性
uni-app(4.85)
| Vue2 | Vue3 | Chrome | Safari | app-vue | app-nvue | Android | iOS | 鸿蒙 |
|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | 5.0 | 12 | 5.0.0 |
| 微信小程序 | 支付宝小程序 | 抖音小程序 | 百度小程序 | 快手小程序 | 京东小程序 | 鸿蒙元服务 | QQ小程序 | 飞书小程序 | 小红书小程序 | 快应用-华为 | 快应用-联盟 |
|---|---|---|---|---|---|---|---|---|---|---|---|
| - | - | - | - | - | - | - | - | - | - | - | - |
ll-wxwork-login
企业微信 SSO 登录 UTS 插件(Android / iOS / 鸿蒙)。
拉起设备上的企业微信客户端完成 OAuth 授权,授权结果通过回调返回给业务层:msg 即企业微信下发的授权 code,交由业务后端调用企业微信服务端接口换取登录态。
鸿蒙端基于
@tencent/wecom_open_sdk(utssdk/app-harmony/libs/lib_wwapi.har),经utssdk/app-harmony/config.json声明依赖。
功能特点
- 三端统一 API:
wxWorkInit注册应用、wxWorkLogin发起授权,接口一致、回调结构一致。 - 拉起企业微信完成 SSO 授权,成功回调直接返回授权
code与透传state。 success/fail互斥且各只会触发一次,complete只触发一次,业务侧无需防重。- 统一错误码体系(9010001–9010008),错误提示为清晰中文并附带原始原因(如
errCode=xxx),便于排查。 - 不含任何 UI,登录入口、loading、错误提示由业务自行控制。
平台兼容性
| 平台 | 支持情况 |
|---|---|
| uni-app Android App(vue) | 支持(minSdkVersion 21) |
| uni-app iOS App(vue) | 支持(deploymentTarget 12.0) |
| uni-app 鸿蒙 App(HarmonyOS 5.0+) | 支持 |
| uni-app x | 不支持 |
| H5 / 各类小程序 / 快应用 | 不支持 |
环境要求:
- HBuilderX 4.85 及以上(插件 engines 最低版本要求;鸿蒙端需使用内置鸿蒙支持的 HBuilderX 版本)。
- 三端均需打自定义基座(云打包 / 本地打包均可),标准基座不包含本插件。
- nvue 页面未验证,建议在 vue 页面中使用。
前置配置
企业微信后台(三端通用)
- 在企业微信管理后台创建自建应用,获取企业 ID
corpId与应用 IDagentId。 - 在应用内配置登录授权回调域名(可信域名)与回调 schema,后续需与代码传入值保持一致。
Android
manifest.json→ App 常用其它设置 → urlschemes 注册应用跳转标识(schema)。- 插件内置
AndroidManifest.xml已声明queries企业微信包名(com.tencent.wework),无需重复配置。
iOS
manifest.json→ App 常用其它设置 → urlschemes 注册 schema(需与传入参数一致)。- 插件已内置
Info.plist的LSApplicationQueriesSchemes(wxwork / wxworklocal),用于企业微信安装检测。 - 重要:插件内置
utssdk/app-ios/Info.plist的CFBundleURLSchemes中包含一个示例 schema(wwauthc8ee6640e64e28da000029)。若你的回调 schema 与之不同,请将该值替换为你自己的 schema,否则企业微信授权完成后可能无法正确回跳应用。
鸿蒙
- schema 在 SDK 内通过
wxWorkInit→registerApp(schema)注册,需与传入参数一致。 - 必须配置:在项目根目录
harmony-configs/entry/src/main/module.json5中声明 querySchemes(与 cms-workwx 官方要求一致),否则 SDK 的canOpenLink('wxworkapi://saas')检测安装会一律返回 false(插件已将安装检查降级为警告,不影响主流程):
{
"module": {
"querySchemes": ["wxworkapi", "https"]
}
}
- 仅支持鸿蒙原生版企业微信;安卓转译版无法被本 SDK 检测/拉起。
- 首次使用需用 HBuilderX(含鸿蒙支持)打自定义基座。
安装与接入
- 通过 HBuilderX 从 DCloud 插件市场导入插件,确认项目中存在
uni_modules/ll-wxwork-login。 - 按上文「前置配置」完成企业微信后台、
manifest.jsonurlschemes、鸿蒙 querySchemes 的配置;iOS 端按需替换内置 Info.plist 中的示例 schema。 - 重新打自定义基座并运行(修改 urlschemes、schema 后同样需重新打基座)。
- 在页面中使用
APP-PLUS || APP-HARMONY条件编译导入并调用。
快速开始
App.vue 启动时注册一次:
// App.vue
<script>
// #ifdef APP-PLUS || APP-HARMONY
import { wxWorkInit } from '@/uni_modules/ll-wxwork-login'
// #endif
export default {
onLaunch() {
// #ifdef APP-PLUS || APP-HARMONY
// 与 manifest.json urlschemes、企业微信后台回调 schema 保持一致
wxWorkInit('wwauthxxxxxxxxxxxxxxx')
// #endif
}
}
</script>
登录页发起授权:
// #ifdef APP-PLUS || APP-HARMONY
import { wxWorkLogin } from '@/uni_modules/ll-wxwork-login'
// #endif
// 点击登录
// #ifdef APP-PLUS || APP-HARMONY
wxWorkLogin({
corpId: 'wwxxxxxxxxxxxxxxxx', // 企业 ID
agentId: '1000002', // 应用 ID
state: 'login_' + Date.now(), // 回带字段,建议携带随机串用于校验
schema: 'wwauthxxxxxxxxxxxxxxx',
success: (res) => {
// res.msg 即企业微信返回的授权 code,交给后端换取登录态
// res.state 为透传的 state,可在此校验
},
fail: (err) => {
// err.code 为错误码,err.msg 为中文提示
uni.showToast({ title: err.msg, icon: 'none' })
},
complete: () => {}
})
// #endif
API 说明
wxWorkInit(schema: string): void
应用启动时调用一次,注册 SDK。
- Android:调用
WWAPIFactory.createWWAPI().registerApp(schema),结果会记录并在wxWorkLogin前置校验。 - iOS:校验 schema 非空并注册
UTSiOS.onOpenURL回调监听(SDK 注册在wxWorkLogin发起授权前执行)。 - 鸿蒙:创建 SDK 实例并
registerApp(schema);wxWorkLogin检测到未注册时会用传入 schema 自动补注册一次。
schema 为空或注册失败时仅输出控制台错误,不抛异常;后续 wxWorkLogin 会以 9010002 / 9010004 失败。
wxWorkLogin(options: LoginOption): void
发起企业微信 SSO 授权,拉起企业微信客户端,授权结果通过回调返回。
LoginOption
| 属性 | 类型 | 必填 | 说明 |
|---|---|---|---|
| corpId | string |
是 | 企业 ID(corpid) |
| agentId | string |
是 | 应用 ID(agentid) |
| schema | string |
是 | 应用跳转标识,需与 manifest.json urlschemes、企业微信后台配置一致 |
| state | string |
否 | 回带字段,默认 'wxwork_auth',建议携带随机串并在回调中校验 |
| success | (res: callBackOption) => void |
否 | 授权成功回调,code=0、msg 为授权 code |
| fail | (err: callBackOption) => void |
否 | 失败回调,code 为错误码、msg 为中文提示 |
| complete | () => void |
否 | 结束回调,成功/失败后各触发一次 |
callBackOption(success / fail 回调参数)
| 属性 | 类型 | 说明 |
|---|---|---|
| code | number |
成功固定为 0;失败为错误码(见下表) |
| msg | string |
成功为企业微信返回的授权 code;失败为错误提示(可能附带原始原因) |
| state | string \| null |
透传的 state(部分场景由 SDK 返回) |
回调约定
success/fail互斥,各只会触发一次;complete在回调结束后触发一次。- 授权
code为一次性凭据,请尽快交由后端换取登录态;插件不处理 token、不缓存 code。 - 所有错误均有错误码与中文提示,便于用户理解与问题排查。
错误码(fail 回调中的 code)
| 错误码 | 含义 | 典型原因 |
|---|---|---|
| 9010001 | 参数错误 | corpId / agentId / schema 为空 |
| 9010002 | 插件未初始化 | 未调用 wxWorkInit 或注册失败后未重试 |
| 9010003 | 未安装企业微信 | 设备上没有企业微信客户端 |
| 9010004 | SDK 注册失败 | manifest 中 urlschemes 与传入 schema 不一致 |
| 9010005 | 拉起企业微信失败 | 企业微信未安装/未登录,或 sendMessage 返回失败 |
| 9010006 | 授权失败 | 用户未在企业微信中确认授权、返回 code 为空等 |
| 9010007 | 用户取消授权 | 用户在企业微信中取消 |
| 9010008 | 未知错误 | SDK 未知错误码或异常,附带原始 errCode/异常信息 |
错误提示会附带原始原因(如 errCode=xxx),便于开发期排查。
使用注意事项
- schema 三处一致:企业微信后台回调 schema、
manifest.jsonurlschemes、wxWorkInit/wxWorkLogin传入值必须完全一致,任一不一致都会导致注册失败(9010004)或回跳失败。 - 修改配置需重打基座:urlschemes、schema、corpid / agentid 变更后,需重新打自定义基座方可生效。
- iOS 回调依赖 openURL:授权回跳依赖
UTSiOS.onOpenURL,自建打包需确认自定义基座包含本插件。 - state 校验:
state用于防止 CSRF,建议携带随机串并在 success 回调(或后端)校验一致性。 - code 换取登录态属业务职责:插件仅返回授权 code,换取 userid / token 需由业务后端调用企业微信服务端接口完成。
- 鸿蒙安装检测已降级:因
canOpenLink白名单限制,鸿蒙端安装检测失败仅输出警告并继续拉起;真正未安装时会以 9010005 失败。 - H5 / 小程序不可用:请使用
APP-PLUS || APP-HARMONY条件编译隔离,H5 端可走企业微信网页授权。 - 并发调用:单次
wxWorkLogin生命周期内回调保证仅触发一次;但不建议同时发起多次授权请求,上一次未回调前再次调用可能出现回调错乱。
常见问题
授权完成后没有任何回调?
依次检查:schema 三处是否一致;iOS 是否替换了插件内置 Info.plist 的示例 schema;是否使用了包含本插件的自定义基座;Android 端企业微信版本是否过旧。
提示 9010004(SDK 注册失败)?
绝大多数为 schema 不一致:核对 manifest.json urlschemes 与传入 wxWorkInit / wxWorkLogin 的值,修改后重新打基座。
鸿蒙端已安装企业微信,却提示拉起失败(9010005)?
确认安装的是鸿蒙原生版企业微信(非安卓转译版),且企业微信已登录;同时检查 harmony-configs 的 querySchemes 是否已按上文配置。
uni-app x 项目能用吗?
暂不支持,当前仅支持 uni-app(vue)项目。
code 交给后端换取登录态失败?
属业务后端与企业微信服务端交互问题,请检查 corpid / agentid / secret 与 code 是否过期(code 为一次性且有时效)。
隐私与依赖说明
基于当前插件源码:
- 插件本身不采集、不存储、不上传任何用户数据,不发起网络请求。
- 仅在授权流程中拉起企业微信客户端,将企业微信返回的授权
code与state通过回调交给业务层;用户身份换取由业务后端与企业微信完成。 - 内置腾讯企业微信开放 SDK:Android(
lib_wwapi-3.0.0.7.aar)、iOS(libWXWorkApi.a)、鸿蒙(lib_wwapi.har,即@tencent/wecom_open_sdk)。 - 无广告、无统计、无其他第三方 SDK。
问题反馈
可通过插件市场反馈问题。建议提供插件版本、HBuilderX 版本、平台(Android / iOS / 鸿蒙)及设备型号、企业微信版本、复现步骤,以及 fail 回调中的错误码和错误提示。请勿提交 corpId、secret、授权 code 等敏感信息。

收藏人数:
购买普通授权版(
试用
赞赏(0)
下载 4
赞赏 0
下载 12777488
赞赏 1960
赞赏
京公网安备:11010802035340号