更新记录

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 页面中使用。

前置配置

企业微信后台(三端通用)

  1. 在企业微信管理后台创建自建应用,获取企业 ID corpId 与应用 ID agentId。
  2. 在应用内配置登录授权回调域名(可信域名)与回调 schema,后续需与代码传入值保持一致。

Android

  1. manifest.json → App 常用其它设置 → urlschemes 注册应用跳转标识(schema)。
  2. 插件内置 AndroidManifest.xml 已声明 queries 企业微信包名(com.tencent.wework),无需重复配置。

iOS

  1. manifest.json → App 常用其它设置 → urlschemes 注册 schema(需与传入参数一致)。
  2. 插件已内置 Info.plist 的 LSApplicationQueriesSchemes(wxwork / wxworklocal),用于企业微信安装检测。
  3. 重要:插件内置 utssdk/app-ios/Info.plist 的 CFBundleURLSchemes 中包含一个示例 schema(wwauthc8ee6640e64e28da000029)。若你的回调 schema 与之不同,请将该值替换为你自己的 schema,否则企业微信授权完成后可能无法正确回跳应用。

鸿蒙

  1. schema 在 SDK 内通过 wxWorkInit → registerApp(schema) 注册,需与传入参数一致。
  2. 必须配置:在项目根目录 harmony-configs/entry/src/main/module.json5 中声明 querySchemes(与 cms-workwx 官方要求一致),否则 SDK 的 canOpenLink('wxworkapi://saas') 检测安装会一律返回 false(插件已将安装检查降级为警告,不影响主流程):
{
  "module": {
    "querySchemes": ["wxworkapi", "https"]
  }
}
  1. 仅支持鸿蒙原生版企业微信;安卓转译版无法被本 SDK 检测/拉起。
  2. 首次使用需用 HBuilderX(含鸿蒙支持)打自定义基座。

安装与接入

  1. 通过 HBuilderX 从 DCloud 插件市场导入插件,确认项目中存在 uni_modules/ll-wxwork-login。
  2. 按上文「前置配置」完成企业微信后台、manifest.json urlschemes、鸿蒙 querySchemes 的配置;iOS 端按需替换内置 Info.plist 中的示例 schema。
  3. 重新打自定义基座并运行(修改 urlschemes、schema 后同样需重新打基座)。
  4. 在页面中使用 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),便于开发期排查。

使用注意事项

  1. schema 三处一致:企业微信后台回调 schema、manifest.json urlschemes、wxWorkInit / wxWorkLogin 传入值必须完全一致,任一不一致都会导致注册失败(9010004)或回跳失败。
  2. 修改配置需重打基座:urlschemes、schema、corpid / agentid 变更后,需重新打自定义基座方可生效。
  3. iOS 回调依赖 openURL:授权回跳依赖 UTSiOS.onOpenURL,自建打包需确认自定义基座包含本插件。
  4. state 校验:state 用于防止 CSRF,建议携带随机串并在 success 回调(或后端)校验一致性。
  5. code 换取登录态属业务职责:插件仅返回授权 code,换取 userid / token 需由业务后端调用企业微信服务端接口完成。
  6. 鸿蒙安装检测已降级:因 canOpenLink 白名单限制,鸿蒙端安装检测失败仅输出警告并继续拉起;真正未安装时会以 9010005 失败。
  7. H5 / 小程序不可用:请使用 APP-PLUS || APP-HARMONY 条件编译隔离,H5 端可走企业微信网页授权。
  8. 并发调用:单次 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 等敏感信息。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

无需额外申请敏感权限;Android 端内置 queries 声明企业微信包名用于安装检测

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

插件本身不采集、不存储、不上传任何用户数据、不发起网络请求;仅拉起企业微信客户端完成授权,将企业微信返回的授权 code 通过回调交给业务层,用户身份换取由业务后端完成

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无广告

暂无用户评论。