更新记录

1.0.0（2026-10-29）

• 新增钉钉官方 SDK 授权码获取、统一公共 API 和错误码，以及 Android、iOS、Harmony 原生桥接实现。
• 新增初始化配置校验、能力检测、钉钉安装状态查询及官方 SDK 支持的 App 内 H5 授权降级。
• 新增安全随机 state、回跳匹配、防重放、单活动会话及重复和迟到回执隔离。
• 新增本地取消、授权超时、忙碌保护及 success/fail/complete 至多一次回调控制。
• 新增脱敏诊断日志、版本与环境快照、完整报告一键复制、固定快照分段复制及手动复制回退。
• 新增 uni-app Vue2/Vue3 与 uni-app x Vapor 示例，支持初始化、能力检查、授权、取消及日志查看。
• 新增后端一次性会话、官方授权码换取令牌与用户信息示例，Client Secret 仅由后端配置。
• 新增 Android Maven、iOS CocoaPods Specs 与 Harmony OHPM 固定依赖配置，以及三端接入和验证范围说明。

平台兼容性

uni-app(5.26)

uni-app x(5.26)

其他

lizhao-dingtalk · 钉钉授权登录 UTS 插件

介绍

通过钉钉官方 SDK 为 uni-app（Vue2/Vue3）和 uni-app x 的移动 App 提供授权登录，向业务代码交付一次性授权码，由业务后端换码并建立登录态。

已提供 Android、iOS、Harmony 原生桥接实现。Android 已完成原生编译和部分真机验收，Harmony 已完成本地原生编译；iOS 已核验 SDK 仓储并修正已知 Swift 接口，仍待 Apple 编译与真机验收。真实账号授权及各项验证边界见“注意事项”。

功能特色

适合哪些场景

下载与导入

从基础到进阶：按业务模块使用

模块一：最小授权路径

示例操作顺序

1. 按“注意事项”完成导入、本端原生配置和钉钉后台登记，使用包含本插件的新源基座或安装包打开对应示例。
2. 页面中的 Client ID、回调地址初始为空，填写自己的配置后点击“初始化”和“检查能力”。Client Secret 仅由后端配置。
3. 完成应用隐私告知后点击“钉钉授权”。体验授权时 state 可留空；真实业务先由后端准备会话，再将后端 state 传入。企业标识权限按实际应用权限选择。
4. 页面显示“已取得授权码；尚未建立业务登录态”时，表示 SDK 已取得一次性授权码；后端换码并返回业务会话后才能认定业务登录成功。授权码只在 success 回调内存中交后端，页面不展示或复制。
5. “取消等待”只结束本地等待，不代表撤销钉钉授权。未取得可关联回执时按真实超时结果处理；success/fail 后另有 complete 摘要。
6. 复现问题后使用底部“一键复制日志”。长报告从固定快照分段，复制失败停留当前段，并提供可见文本框手动复制。完整报告保留版本、环境、原生诊断及本次操作轨迹。

用户阅读并同意应用隐私告知后，再执行初始化和主动授权。Client ID 和回调地址来自自己的钉钉应用，不要把 Client Secret 放入 App。以下代码可放入示例的业务事件函数，导入位置保持不变：

import { initDingTalk, loginWithDingTalk } from '@/uni_modules/lizhao-dingtalk'

const initialized = initDingTalk({
  clientId: '替换为真实ClientID',
  redirectUri: 'https://your-domain.example/auth/dingtalk/callback'
})
if (initialized.ok) {
  loginWithDingTalk({
    scope: 'openid',
    timeoutMs: 120000,
    success: (result) => {
      // 仅把result.authCode/state交自己的后端；不要打印、复制或持久化。
      uni.showToast({ title: '已取得授权码，待后端登录', icon: 'none' })
    },
    fail: (error) => {
      uni.showToast({ title: error.errCode + '：' + error.errMsg, icon: 'none' })
    },
    complete: (result) => {
      // 此回调不含授权码，可用于结束按钮等待态。
      console.log('授权流程结束', result.requestId, result.errCode)
    }
  })
} else {
  uni.showToast({ title: initialized.errMsg, icon: 'none' })
}

上面的输入必须替换为真实配置。完整可操作页面为 uni_modules/lizhao-dingtalk/example/uniapp/index.vue 和 uni_modules/lizhao-dingtalk/example/uniappx/index.uvue；示例不会替业务应用自动向外部服务器发送授权码。

模块二：后端换码和业务会话

随插件交付的 uni_modules/lizhao-dingtalk/server-example/dingtalk.cjs 使用真实官方接口：POST /v1.0/oauth2/userAccessToken 换码，再 GET /v1.0/contact/users/me 读取当前用户，需要 Contact.User.Read 权限。Client Secret 仅由后端环境变量提供，示例不返回钉钉 accessToken/refreshToken 给 App。

安装 Node.js 22 或以上，将环境变量 DINGTALK_CLIENT_ID、DINGTALK_CLIENT_SECRET 配置到运行该服务的环境，再运行：

node uni_modules/lizhao-dingtalk/server-example/server.cjs

此参考服务仅监听本机 127.0.0.1:18731，没有自动部署。生产须接入自己的 HTTPS 网关、会话、数据库与限流。内存会话重启即失效。

使用者后端应配置自己的 DINGTALK_CLIENT_ID 与 DINGTALK_CLIENT_SECRET，前者与 App 中使用的 Client ID 相同。真机中的 127.0.0.1 指向手机本身；这里的本机地址只用于后端参考验证，业务 App 需要调用使用者已部署、可访问的 HTTPS 服务。

1. App POST /auth/dingtalk/prepare，JSON 为 {}，取得一次性 flowToken 和 state。准备会话有效 300 秒。
2. 将收到的 state 原样传入 loginWithDingTalk；不要用时间戳、固定字符串或本地永久值替代后端 nonce。
3. 在 success 中 POST /auth/dingtalk/login，发送 JSON {flowToken, state: result.state, authCode: result.authCode}；这些值只在内存短暂保留，不写日志。
4. 服务验证准备会话/state、单次消费，再调用钉钉换码。成功返回独立业务 sessionToken 和已验证用户。使用 Authorization: Bearer <sessionToken> 调用参考服务 POST /session/me。业务账号绑定应由自己的后端完成。

失败后重新准备会话并授权，不自动重复消费旧 authCode。服务端参考的单次消费不能代替业务端的账号绑定、防重放和访问控制。

两个交付示例默认只演示 SDK 授权码获取。业务接入点为 uni_modules/lizhao-dingtalk/example/page.template 的 login 方法及其 success 回调：发起授权前准备后端会话，将后端 state 传入插件；成功后把结果交自己的换码接口。页面中“已取得授权码”表示 SDK 成功，后端返回业务会话之后才能显示业务登录成功。维护示例时改主模板并运行生成器，保持 uni_modules/lizhao-dingtalk/example/uniapp/index.vue 和 uni_modules/lizhao-dingtalk/example/uniappx/index.uvue 同源。

模块三：取消、能力检查和诊断

import { getDingTalkCapabilities, loginWithDingTalk, cancelDingTalkLogin, getDingTalkDiagnostics, clearDingTalkDiagnostics } from '@/uni_modules/lizhao-dingtalk'

const capabilities = getDingTalkCapabilities()
if (capabilities.nativeSupported && capabilities.initialized) {
  const requestId = loginWithDingTalk({
    fail: (error) => { console.log('流程错误码', error.errCode) },
    complete: (result) => { console.log('流程结束', result.requestId, result.errCode) }
  })
  // 在用户点击“取消等待”或页面卸载时执行；不会撤销钉钉授权。
  cancelDingTalkLogin(requestId)
}
const snapshot = getDingTalkDiagnostics()
console.log('脱敏日志条数', snapshot.logs.length)
// 清理插件日志不会取消授权；示例页面缓存/已有报告快照继续保留。
clearDingTalkDiagnostics()

示例的“一键复制日志”包含环境、完整插件快照和保留的操作记录，屏幕仅显示最近摘要。更新快照后从第一段开始；复制失败不推进。页面提供完整报告和可选中文本的手动回退，不自动上传。

API 用途速查

初始化参数和结果

DingTalkInitResult 含 ok:boolean、initialized:boolean、errSubject:string、errCode:number、errMsg:string、platform:string、sdkVersion:string。初始化失败不抹除仍在等待的旧会话；以本次 ok 判断配置是否成功。

登录参数、回调和取消

DingTalkLoginSuccess 含 errSubject、errCode=0、errMsg、requestId、platform、authCode、state，字符串字段不得当用户身份使用。DingTalkCompleteResult 仅含前五个摘要字段，没有授权码。DingTalkFail 另含 nativeCode、nativeType、nativeCause、nativeStack；原生未提供时明确 unknown。

DingTalkCancelResult 含 errSubject/errCode/errMsg/requestId 和 cancelled:boolean。false 代表没有匹配会话或发生错误，应同时看 errCode；true 表示本地确实取消，原 login 接着收到 9358010 和 complete。未安装钉钉时允许 SDK 尝试 H5，具体能力见快照。

能力、诊断与生命周期

DingTalkCapabilities 含 platform、nativeSupported、initialized、installed（installed/notInstalled/unknown）、sdkVersion、packageName、nativeBuildId、canFallbackToWeb 和 limitations:string[]。原生能力可用不代表开放平台配置、网络或用户授权已经通过。

DingTalkDiagnostics 含 pluginId、pluginVersion、buildId、generatedAt、platform、logs:string[]、droppedLogs:number、nativeSnapshot:string。插件版本从 package 自动生成；报告的源码构建标记不冒充使用者安装包的 HX/原生基座版本。无法取得的环境值标记 unknown 和来源。

一次只允许一个活动请求。自定义 state 在本进程不可复用，最多记录1024个摘要，达到上限后可省略 state 使用原生随机路径；生产业务也应在后端限制会话与重放。进程被回收后旧页面回调不能恢复，应重新发起。无持续事件监听，也不需要订阅释放；页面卸载可取消本页仍在等待的请求。

错误码说明

所有业务错误的 errSubject 固定为 lizhao-dingtalk。0 表示当前 API 成功；授权成功并不表示后端登录已成功。

用户切回 App 不等于取消；部分 SDK H5 关闭时没有取消回执，将继续等待到超时。未知错误不能转换成成功或空授权码。

注意事项

导入与示例注册

保留完整 uni_modules/lizhao-dingtalk/ 目录复制到项目，页面只从 @/uni_modules/lizhao-dingtalk 导入。当前是源码交付，没有可用市场下载地址，不要拆出内部文件或跨插件引用。

• uni-app：将 uni_modules/lizhao-dingtalk/example/uniapp/index.vue 注册到 pages.json，路由省略扩展名。示例为选项式 API，兼容 Vue2/Vue3。
• uni-app x：注册 uni_modules/lizhao-dingtalk/example/uniappx/index.uvue，使用 script setup，适用于 Vapor。导航栏标题建议“钉钉授权登录”。
• 两页由 uni_modules/lizhao-dingtalk/example/page.template 生成；纯 JS 报告放在 uni_modules/lizhao-dingtalk/static/report.js，原始报告位于 uni_modules/lizhao-dingtalk/example/report.uts。维护源码后运行项目脚本 node scripts/build-dingtalk-examples.cjs，再用 --check 核对。
• 原生依赖和生命周期需要重新原生联编或重打自定义基座。标准基座及旧基座不能仅靠 WGT 增加 SDK。

应用配置清单

插件不附带可供使用者共用的钉钉应用。示例中的 Client ID 和回调地址初始为空，由使用者使用自己的钉钉移动应用配置填写。文中的“替换为真实”以及 your-domain.example 都是待替换的说明值。

redirectUri 用于 SDK 的钉钉配置校验；App 回执由原生 Activity、URL Scheme 或 Want 返回。不要以该 HTTPS 地址是否收到请求作为 SDK 授权完成的判断依据，业务状态以 success/fail/complete 为准。

Android 配置

最低 Android API 21。固定 Maven 依赖 com.alibaba.android:ddopenauth:1.5.0.10 自动解析，不需要手动复制 AAR。uni_modules/lizhao-dingtalk/utssdk/app-android/AndroidManifest.xml 包含 INTERNET、钉钉精确包查询和回跳别名，不申请全量应用列表、通讯录或存储权限。

在钉钉后台登记最终应用包名和签名；使用自定义基座时，后台登记必须与实际安装包一致。Manifest 会将 ${applicationId}.ddauth.DDAuthActivity 映射到插件回调 Activity，不要再在宿主添加同名 Activity。SDK H5 页面由官方依赖合并。

iOS 配置与依赖门槛

最低 iOS 12.0，官方 SDK 为 ADTOpenAuthSDK 0.0.1.16。插件已配置自有索引 LZDingTalkOpenAuth，原生模块仍为官方 ADTOpenAuthSDK。公开 Specs 来源为 钉钉 SDK 索引，仓储目录 https://env-00jxu7ha8amh.normal.cloudstatic.cn/lizhao-dingtalk/。2026-10-28 已通过原版 CocoaPods Core 从空缓存发现和解析固定版本，再由原版 Downloader 实际下载、SHA-256 校验并解压官方 SDK，核对 19 个文件及资源路径。这些检查不等于完整 pod install、Apple 编译或真机授权成功。

保留原生配置后，联编或云打包时从仓储解析固定依赖，SDK 直接取自钉钉官方归档，不需使用者另行上传索引或手动复制 XCFramework。native-sdk-repositories/dingtalk-ios/ 是项目维护材料，不参与客户端授权。Podspec 为 Objective-C 链接配置 -ObjC；dependencies-pod-resources=app 把 SDK H5 返回图标放入主应用资源。

依赖配置位于 uni_modules/lizhao-dingtalk/utssdk/app-ios/config.json。URL 查询列表位于 uni_modules/lizhao-dingtalk/utssdk/app-ios/Info.plist。接入时还须合并自己的 URL Scheme：

<key>CFBundleURLTypes</key>
<array><dict>
  <key>CFBundleURLName</key><string>dingtalk</string>
  <key>CFBundleURLSchemes</key><array><string>替换为真实ClientID</string></array>
</dict></array>

把上述 CFBundleURLTypes 合并到该文件现有的 <dict> 中，保留钉钉查询白名单和其他插件配置，不用这段内容替换整个 Info.plist。Scheme 必须等于同一应用的真实 Client ID。修改 Scheme 后重新原生联编或打包；只修改页面输入框不能改变安装包已注册的 Scheme。

实际 Bundle ID 必须与钉钉后台一致；iosBundleId 仅用于额外核对，不修改宿主标识。UTS 生命周期代理自动转发本插件 URL，不需要修改 AppDelegate。原生桥在 SDK 未接入时返回 9358004，能力中的 nativeSupported=false。

Harmony 配置

固定依赖为官方 OHPM @dingtalk/openauth:1.1.0，配置在 uni_modules/lizhao-dingtalk/utssdk/app-harmony/config.json。SDK 要求 Harmony API 15 及以上；本轮 HBuilderX 5.33 的 Vapor 运行库要求 API 20，因此实际最低版本须取 SDK 与当前宿主运行库要求中的较高值。后台登记应用 appIdentifier，不能用 appId 代替。回跳 Ability 默认 EntryAbility，更改宿主 Ability 名称时使用 harmonyAbilityName。

插件使用真实 ArkUI 组件承载官方授权页，处理 onCreate / onNewWant 的授权回执。还须配置宿主查询白名单和可回跳的 Ability：

1. 宿主已有 harmony-configs/entry/src/main/module.json5 时，在其完整内容中合并。没有时，从当前 HBuilderX、当前项目及实际渲染模式生成的完整 Harmony 原生工程复制 entry/src/main/module.json5 到这个位置。此文件由宿主构建生成，不是随插件交付的文件。
2. 在完整文件的 module.querySchemes 数组追加并去重 dingtalk；保留原有 scheme。核对最终权限包含 ohos.permission.INTERNET。插件 uni_modules/lizhao-dingtalk/utssdk/app-harmony/module.json5 已声明网络权限，查询白名单必须放在宿主 entry 清单。
3. 在 module.abilities 中定位实际回跳 Ability，设置该项 exported=true，保留其 srcEntry、skills、页面、资源及其他字段。该入口接收外部 Want，插件会校验官方 action 和会话 state。
4. 需要调整宿主 harmony-configs/build-profile.json5 时，同样从完整现有或本次生成文件合并，仅提高实际目标 product 的兼容 SDK，保留产品、模块及签名引用；已有更高版本不降低。当前 Vapor 至少 API 20，传统 Vue3 至少 API 15。

harmony-configs 是整文件覆盖，不是字段合并。不能把只有 querySchemes 的片段保存成完整清单，也不能复制插件 HAR 清单或其他宿主的清单代替。打包后再次核对完整 entry 配置和 product；当前两项目没有自动生成这两个宿主配置文件。

本轮生产 ETS、真实 OHPM、独立未签名 HAP，以及 uni-app x Vapor / uni-app Vue3 的实际生成 UTS 与对应运行库 HAR 联编通过，保留原始 ArkTS 告警。Vue2 Harmony 在本机因缺少平台编译插件未完成；设备授权、H5 回退及完整宿主运行仍待验收。用户关闭 H5 时 SDK 不保证给取消回执，本地会继续等待至显式取消或超时，不把页面返回视为授权取消。

平台与验证范围

平台元数据使用 √ 表示支持、x 表示不支持、- 表示待确认；当前 iOS 保留 -。支持标记不代表已完成所有系统版本和真实账号业务验收。示例暂不声明暗黑模式、多语言和宽屏适配。业务验收需要已审批的 Client ID、回调地址、各端应用登记信息、真实用户主动授权及匹配新源的安装包；本插件不包含钉钉分享能力。

隐私、配置与发布

不把 Client Secret、钉钉 token、原始授权码、原始 state 或个人资料写进客户端配置、控制台、崩溃日志或诊断。后台应验证一次性会话，将钉钉用户身份映射自己的账号。官方第三方 SDK 的隐私政策与权限须在业务隐私告知中说明，插件不会自动同意授权。

新增或修改原生源码、SDK、Manifest、Info.plist、Harmony配置后必须重新原生联编或重打对应自定义基座；WGT/appResource 不能更新旧 Native。iOS 需 Apple 工具链实际验证SDK依赖和Swift；Harmony需正确SDK及签名环境。

示例报告只在内存保留，容量1000条/1MiB UTF-8，包含丢弃数量；公共诊断另有240条/64Ki字符上限，原生上限见快照。报告脱敏失败不应改变授权业务结果。系统剪贴板和真机展示需要在实际目标设备检查；模拟复制回执或静态守卫不能代替系统验收。

作者系列 UTS 插件

以下为统一清单中已核实的作者插件；本候选插件未列为已发布。