更新记录

1.3.0（2026-08-24）

• 新增：verifyTokenRemote 远程校验登录态（token 被服务端拉黑/过期时自动清理本地登录态并触发登出事件；网络异常保留本地登录态返回 false）
• 新增：onLoginStateChange 返回注销函数，页面销毁时调用即可取消监听，避免内存泄漏
• 文档：新增「重要限制」章节前置高亮硬性限制（uni-id-co 依赖、云对象名固定、加密版仅云打包、微信企业主体、isInstalled、模拟器一键登录、短信防抖、远程校验）
• 文档：补充 9010005 定位（错误消息附带原始 errMsg）、鸿蒙错误文本（以 errCode 判断）、本地缓存与服务端 token 不一致处理等常见问题

1.2.0（2026-08-24）

• 修复：loginBySms 支持图形验证码 captcha（uni-id 开启强制图形验证码时透传，避免登录失败）
• 修复：示例占位 uni-id-co 补齐全部接口，未部署真实 uni-id-co 时返回明确提示而非运行时抛错
• 修复：getUserInfo 在 Android / iOS 微信下正确提取 openid
• 优化：删除未实际抛出的错误码 9010011 ~ 9010014，错误码表与代码保持一致
• 优化：文档措辞统一为「服务端返回新 token 时自动更新本地缓存」，并补充登录态存储安全说明
• 文档：示例中的手机号改为占位符，规避插件市场隐私信息过滤

1.1.0（2026-08-24）

• 新增运营商一键登录 loginByUniverify（含注册，自动预登录 + 标准登录）
• 新增短信验证码能力：sendSmsCode 发送验证码、loginBySms 短信登录（含注册）
• 新增绑定手机号：bindMobileByUniverify、bindMobileBySms，绑定成功自动续期 token
• 新增 token 续期 refreshToken，token 失效自动清理登录态
• 新增用户中心：getAccountInfo 账户简略信息、unbindProvider 解绑渠道
• 新增登录态事件 onLoginStateChange / offLoginStateChange，登录/登出/token 过期自动触发
• 示例工程新增一键登录、短信登录、用户中心、登录态事件演示
• 新增错误码 9010009 ~ 9010014

平台兼容性

uni-app x(4.25)

kyokasangi-login 多端统一登录插件

基于 uni-app x 内置 OAuth 能力，一行代码实现 微信 / Apple / 华为账号 登录，并内置运营商一键登录、短信验证码登录，全量集成 uni-id（uniCloud）完整登录链路（授权换 token、绑定手机号、用户中心、登录态检测与事件监听）。

特性

• ✅ 三端统一：一套 API 覆盖 Android / iOS / HarmonyOS
• ✅ 三方登录：微信登录（三端）、Apple 登录（iOS）、华为账号登录（HarmonyOS）
• ✅ 手机号登录：运营商一键登录（uni.getUniVerifyManager）+ 短信验证码登录/发送
• ✅ 绑定手机号：支持一键登录 / 短信验证码两种方式绑定，绑定成功若服务端返回新 token 则自动更新本地缓存
• ✅ 免原生 SDK：完全基于 uni-app x 内置 OAuth 能力，无需集成第三方原生 SDK
• ✅ uni-id 闭环：内置 loginWithUniId，授权后自动调用 uniCloud 云对象换取 token 并缓存登录态
• ✅ token 续期：refreshToken 主动续期（服务端返回新 token 时自动更新本地缓存），token 失效自动清理登录态
• ✅ 远程校验：verifyTokenRemote 服务端校验 token 是否有效，token 被拉黑/过期时自动登出
• ✅ 用户中心：getAccountInfo 获取账户简略信息、unbindProvider 解绑渠道
• ✅ 登录态事件：onLoginStateChange 监听登录/登出（返回注销函数），配合登录页跳转
• ✅ 登录态管理：checkLoginState 检测登录态、logout 一键登出
• ✅ 安装检测：isInstalled 判断微信是否安装（iOS 审核要求；Android/HarmonyOS 恒返回 true）
• ✅ 开箱即用：附带完整示例工程

适用平台

依赖 HBuilderX 5.08+（Android/iOS 微信登录）、5.21+（iOS Apple 登录）、4.61+（鸿蒙华为登录）、4.42+（一键登录）。当前示例基于 HBuilderX 5.24 开发。

⚠️ 重要限制（使用前必读）

以下为本插件的硬性限制与已知注意事项，与功能缺陷无关，属平台与产品设计使然，请提前评估是否满足你的业务场景。

1. 必须搭配 uni-id-co 使用：登录 / 绑定 / 续期 / 登出等全部依赖 uniCloud 官方云对象 uni-id-co。本插件不含 uni-id-co 实现，导入后需自行在 uniCloud/cloudfunctions 创建 uni-id-co（uni_modules 内置版本或使用插件附带的示例占位云对象均可），并完成 uni-id 配置（uni-config-center/uni-id/config.json）。
2. 云对象名固定为 uni-id-co：受 uni-app x 强类型限制，uniCloud.importObject 的云对象名必须是编译期字面量，插件固定调用 uni-id-co，无法通过配置改名。若你自定义了云对象名，需直接修改插件源码（源码版可改）。加密版不可改。
3. 加密版仅限云端打包：普通版由 DCloud 对 uts 源码加密保护，不支持本地离线打包（离线打包需源码版）。
4. 微信登录要求企业主体：微信开放平台「移动应用」认证仅面向企业，个人开发者无法开通微信登录。
5. isInstalled 仅 iOS 真实检测：Android / HarmonyOS 上 isInstalled 恒返回 true（平台限制），仅 iOS 能真实判断微信是否安装。
6. 一键登录在模拟器上不可用：运营商一键登录依赖真实 SIM 卡环境，模拟器 / 无 SIM 卡设备上预登录必然失败。
7. 短信发送受频率限制：uni-id 默认对同一手机号有发送间隔限制，连点「发送验证码」会触发「操作过于频繁」类错误，请自行对按钮做防抖（60s 倒计时）。
8. 绑定/解绑与本地登录态：绑定手机号成功后若服务端返回新 token 会自动更新本地缓存；checkLoginState 仅检测本地缓存，服务端 token 是否仍有效需调用 verifyTokenRemote 远程校验（token 被拉黑/过期时自动清理本地登录态并触发登出事件）。

版本与定价

两版本功能完全一致，差异在于源码可见性与可定制性。付费版本由插件市场加密分发，保证源码版权益。

安装

方式一：插件市场导入（推荐）

1. 在 DCloud 插件市场搜索「多端统一登录」或插件 ID kyokasangi-login
2. 点击"购买/导入"，使用 HBuilderX 导入到项目 uni_modules 目录
3. 导入后即可使用

方式二：手动复制

将 uni_modules/kyokasangi-login 整个目录复制到你的 uni-app x 项目根目录 uni_modules/ 下。

快速接入

只需三步：

第一步：配置 manifest.json

按需在 manifest.json 中配置各端 uni-oauth 模块与 univerify 一键登录模块（未启用渠道可不配）：

{
  // Android：微信登录 + 一键登录
  "app-android": {
    "distribute": {
      "modules": {
        "uni-oauth": {
          "weixin": {
            "appid": "你的微信开放平台APPID"
          }
        },
        "univerify": {
          "appid": "DCloud一键登录应用ID",
          "appkey": "DCloud一键登录应用Key"
        }
      }
    }
  },
  // iOS：微信 + Apple 登录 + 一键登录
  "app-ios": {
    "distribute": {
      "modules": {
        "uni-oauth": {
          "weixin": {
            "appid": "你的微信开放平台APPID",
            "universalLink": "https://你的域名/微信关联域名"
          },
          "apple": {}
        },
        "univerify": {
          "appid": "DCloud一键登录应用ID",
          "appkey": "DCloud一键登录应用Key"
        }
      }
    }
  },
  // HarmonyOS：微信 + 华为账号登录 + 一键登录
  "app-harmony": {
    "distribute": {
      "modules": {
        "uni-oauth": {
          "weixin": {
            "appid": "你的微信开放平台APPID"
          },
          "huawei": {}
        },
        "univerify": {
          "appid": "DCloud一键登录应用ID",
          "appkey": "DCloud一键登录应用Key"
        }
      }
    }
  }
}

一键登录：appid/appkey 需在 DCloud 开发者中心 开通「App一键登录」服务后获取，按次计费。未开通时调用 loginByUniverify 会返回 1000 错误码。

短信验证码：需在 DCloud 开发者中心开通「短信服务」并充值（发送验证码按条计费），短信模板在 uni-id 服务端配置。

第二步：部署 uni-id 服务端

详见插件内 uniCloud/README.md。核心：部署 uni-id-co 云对象 + 配置 uni-config-center/uni-id/config.json 中的各渠道 appid/secret。

第三步：调用登录

import { loginWithUniId } from '@/uni_modules/kyokasangi-login/utssdk/index.uts'

loginWithUniId({
  provider: 'weixin', // weixin | apple | huawei
  success: (res) => {
    console.log('token:', res.token)
    console.log('uid:', res.uid)
    console.log('userInfo:', res.userInfo)
  },
  fail: (err) => {
    console.log('登录失败:', err.errCode, err.errMsg)
  }
})

各渠道接入准备

微信登录（需要企业主体 ⚠️）

重要：微信开放平台仅支持企业主体注册移动应用。个人开发者无法申请微信登录，请提前准备营业执照。

1. 前往 微信开放平台 注册账号并完成企业认证
2. 创建「移动应用」，获取 AppID 与 AppSecret
3. 填写 Android 应用签名、iOS Universal Links 等校验信息
4. 将 AppID 填入 manifest.json 各端 weixin.appid，AppSecret 填入 uni-id config.json

Apple 登录（iOS）

1. 在 Apple Developer 开启「Sign in with Apple」能力
2. 在 Xcode 工程 Capabilities 中添加 Sign in with Apple（或在 HBuilderX 离线打包工程中配置）
3. manifest.json 的 app-ios 中启用 uni-oauth.apple
4. 无需额外的 appid/secret（使用 identityToken 校验）

华为账号登录（HarmonyOS）

1. 在 AppGallery Connect 创建应用，开启「华为账号服务」
2. 获取 Client ID 与 Client Secret，填入 uni-id config.json 的 huawei
3. manifest.json 的 app-harmony 中启用 uni-oauth.huawei

API 文档

说明：uni-app x 强类型限制，uniCloud.importObject 的云对象名必须是编译期字面量。 插件固定调用 uni-id-co 云对象，若你自定义部署了云对象名，请在源码中直接修改（源码版可改）。

授权登录（仅取 code）

login(options: LoginOptions): void

LoginSuccess：

集成 uni-id 登录（推荐）

loginWithUniId(options: UniIdLoginOptions): void

UniIdLoginResult：

获取用户信息

getUserInfo(options: GetUserInfoOptions): void

检测登录态

checkLoginState(): UTSJSONObject | null

返回本地缓存的登录信息（含 token/tokenExpired/uid/openId/provider/userInfo），未登录或已过期返回 null。

仅检测本地缓存，不访问网络。若需确认 token 在服务端仍有效（如 token 被拉黑、账号被封禁），请调用 verifyTokenRemote 远程校验。

退出登录

logout(): Promise<boolean>

调用 uni-id-co 登出并清除本地登录态，返回 true 表示登出成功。

判断渠道是否安装

isInstalled(provider: LoginProvider): boolean

iOS 上微信未安装时返回 false（可据此隐藏微信登录按钮以通过审核）。

局限：Android / HarmonyOS 上因平台 API 限制，无法可靠判断微信是否安装，恒返回 true，仅 iOS 可真实检测。

获取可用渠道

getProviders(): string[]

返回当前平台可用的渠道列表，如 ['weixin']。

运营商一键登录（含注册）

loginByUniverify(options: UniverifyLoginOptions): void

封装 uni.getUniVerifyManager：自动预登录 -> 标准登录（拉起运营商授权页）-> 调用 uni-id-co loginByUniverify 换取 token。未注册用户自动注册并登录。

需先在 DCloud 开发者中心开通一键登录服务并在 manifest.json 配置 appid/appkey。用户取消登录时错误码为 30001，可按需转为短信验证码登录。

短信验证码登录（含注册）

loginBySms(options: SmsLoginOptions): void

发送短信验证码

sendSmsCode(options: SendSmsCodeOptions): void

需在 DCloud 开发者中心开通短信服务并充值，并在 uni-id config.json 中配置短信模板。

绑定手机号（一键登录）

bindMobileByUniverify(): Promise<boolean>

使用运营商一键登录绑定手机号，绑定成功若服务端返回新 token 则自动更新本地缓存。

绑定手机号（短信验证码）

bindMobileBySms(options: BindMobileBySmsOptions): Promise<boolean>

绑定成功若服务端返回新 token 则自动更新本地缓存。

刷新 token（续期）

refreshToken(): Promise<boolean>

调用 uni-id-co refreshToken 续期（仅当 token 即将过期时服务端才会返回新 token），成功后自动更新本地缓存登录态。token 已失效时自动清除本地登录态并触发登出事件。

远程校验登录态

verifyTokenRemote(): Promise<boolean>

服务端校验本地 token 是否有效：

• token 有效：返回 true（若服务端返回新 token 则自动更新本地缓存登录态）
• token 已被服务端拉黑 / 已过期：自动清除本地登录态并触发登出事件，返回 false
• 网络 / 云对象异常：无法确认 token 状态，保留本地登录态，返回 false

uni-id-co 未暴露独立的 checkToken 客户端接口，本方法以 refreshToken 作为远程校验手段（token 失效时它会返回错误）。适合在 App 启动、进入需登录页面时调用，弥补 checkLoginState 仅查本地缓存的局限。

获取账户简略信息

getAccountInfo(): Promise<AccountInfo | null>

需登录后调用。AccountInfo 字段：isUsernameSet / isNicknameSet / isPasswordSet / isMobileBound / isEmailBound / isWeixinBound / isQQBound / isAlipayBound / isAppleBound。

解绑登录渠道

unbindProvider(provider: LoginProvider): Promise<boolean>

解绑微信 / Apple / 华为账号渠道，返回 true 表示成功。

仅支持解绑本插件内置渠道（weixin / apple / huawei）；其他第三方渠道未接入，无法通过本插件解绑，可在 uniCloud 控制台或自建后端处理。

监听登录态变更

onLoginStateChange(callback: LoginStateChangeCallback): () => void
offLoginStateChange(callback: LoginStateChangeCallback): void

type LoginStateChangeCallback = (isLogin: boolean, state: UTSJSONObject | null) => void

登录成功、token 续期、绑定手机号、登出、token 过期自动登出时均会触发。isLogin 为 false 且 state 为 null 表示已登出。

onLoginStateChange 返回注销函数，页面销毁时调用即可取消监听，避免内存泄漏（推荐用法）：

let offLogin: (() => void) | null = null
onLoad(() => {
    offLogin = onLoginStateChange((isLogin, state) => {
        // 处理登录/登出
    })
})
onUnload(() => {
    if (offLogin != null) {
        offLogin()
        offLogin = null
    }
})

典型用法：App.vue 中监听并跳转登录页。

错误码

说明：绑定/解绑/续期/获取账户信息等 Promise 类接口（返回 boolean 或对象）失败时统一返回 false/null，不额外抛出错误码。

其他错误码（如 1310500 系列）为 uni 内置 API 透传，可参考 uni.login 错误码文档。一键登录返回的 30001（取消登录）、1000（未开通）等为 uni 一键登录错误码。

完整示例

import {
  loginWithUniId,
  loginByUniverify,
  loginBySms,
  sendSmsCode,
  bindMobileByUniverify,
  refreshToken,
  verifyTokenRemote,
  getAccountInfo,
  unbindProvider,
  onLoginStateChange,
  login,
  getUserInfo,
  checkLoginState,
  logout,
  isInstalled,
  getProviders
} from '@/uni_modules/kyokasangi-login/utssdk/index.uts'

// 0. 监听登录态变更（App.vue 中，用于登录页跳转等）
onLoginStateChange((isLogin, state) => {
  if (isLogin) {
    // 已登录，关闭登录页
  } else {
    // 已登出，跳转登录页
  }
})

// 1. 判断微信是否安装
if (isInstalled('weixin')) {
  // 显示微信登录按钮
}

// 2. 三方登录（授权 + 换 token）
loginWithUniId({
  provider: 'weixin',
  success: (res) => {
    // 登录成功，token 已自动缓存
  },
  fail: (err) => {
    // 登录失败
  }
})

// 3. 运营商一键登录
loginByUniverify({
  success: (res) => {
    // 一键登录成功
  },
  fail: (err) => {
    if (err.errCode == 30001) {
      // 用户取消，可转短信登录
    }
  }
})

// 4. 短信验证码登录
sendSmsCode({
  mobile: '请输入手机号',
  scene: 'login-by-sms',
  success: () => {
    // 验证码已发送
  }
})
loginBySms({
  mobile: '请输入手机号',
  code: '123456',
  success: (res) => {
    // 短信登录成功
  }
})

// 5. 刷新 token（续期）
await refreshToken()

// 6. 获取账户信息（登录后）
const info = await getAccountInfo()
if (info != null && !info.isMobileBound) {
  // 引导绑定手机号
  await bindMobileByUniverify()
}

// 7. 解绑渠道
await unbindProvider('weixin')

// 8. 只拿授权 code（自行处理后端）
login({
  provider: 'weixin',
  success: (res) => {
    console.log('code:', res.code)
  }
})

// 9. 获取用户信息（登录后）
getUserInfo({
  provider: 'weixin',
  success: (res) => {
    console.log('昵称:', res.nickName, '头像:', res.avatarUrl)
  }
})

// 10. 检测登录态
const state = checkLoginState()
if (state != null) {
  // 已登录
}

// 11. 退出登录
await logout()

安全说明

• 登录态本地存储：登录后 token / tokenExpired 等以明文形式存于应用本地 Storage（uni_id_token 键）。App 端数据位于应用私有沙箱内，普通用户无法直接读取；但若设备已 root/越狱，理论上可被读取。
• 建议：高安全场景下可在 uni-id config.json 中调短 tokenExpiresIn，并在关键业务（下单、支付等）额外调用云函数校验 token 有效性，而非仅依赖本地登录态。
• 请勿在客户端暴露任何私钥 / AppSecret；服务端密钥一律存放于 uniCloud 云端。

常见问题

Q：登录报 9010005 uni-id 调用失败？ A：先检查 uni-id-co 是否已部署、uni-config-center/uni-id/config.json 是否已上传、各渠道 appid/secret 是否填写正确。9010005 的错误消息会附带原始错误详情（errMsg 字段），据此可进一步定位：若提示云对象/云函数不存在，说明 uni-id-co 未部署或云对象名不一致；若提示超时/网络错误，说明网络或云端服务异常。

Q：iOS 上微信登录按钮点击无反应？ A：确认 Universal Links 已在微信开放平台配置，且 manifest.json 的 universalLink 与之匹配。

Q：个人开发者能否使用微信登录？ A：不能。微信开放平台要求企业主体，请提前准备营业执照完成认证。

Q：为何 iOS 必须同时提供 Apple 登录？ A：App Store 审核要求：使用了其他第三方登录，必须同时提供"通过 Apple 登录"。本插件已内置，启用即可。

Q：可以自定义 uni-id-co 名称吗？ A：uni-app x 强类型限制，importObject 的云对象名必须是编译期字面量，插件固定调用 uni-id-co。若你自定义了云对象名，需直接修改插件源码中的 uniCloud.importObject('uni-id-co')（源码版可改）。

Q：一键登录返回错误码 1000 / 30001？ A：1000 表示当前 appid 未开通一键登录服务，请到 DCloud 开发者中心开通并配置 manifest.json 的 univerify.appid/appkey，同时检查账号余额；30001 表示用户取消了登录，可引导用户改用短信验证码登录。

Q：鸿蒙（HarmonyOS）上报错文本与文档示例不一致？ A：鸿蒙平台错误对象的 errMsg 文本格式与其他平台不同（如登出提示语可能含 NO_USE 字样，且不保证包含 errCode 关键词）。请一律以 err.errCode 数值判断错误类型（本插件内部统一按 errCode != 0 判断，不受影响）；若业务代码按错误文案解析，请改为按错误码判断。

Q：发送短信验证码失败？ A：检查是否已在 DCloud 开发者中心开通短信服务并充值；若 uni-id config.json 强制图形验证码（needCaptcha），需先接入图形验证码并将 captcha 传入 sendSmsCode。

Q：checkLoginState 显示已登录，但服务端 token 已失效？ A：checkLoginState 仅检测本地缓存，服务端状态需网络校验。调用 verifyTokenRemote 即可：token 有效返回 true，token 被服务端拉黑/过期时自动清理本地登录态并触发登出事件。

Q：如何扩展更多第三方登录渠道？ A：源码版可在 utssdk 分平台目录扩展自定义 provider，或基于 login 的 code 自行对接服务端。购买源码版免费升级获取后续内置渠道。

许可

• 普通版 / 源码版均按 DCloud 插件市场授权协议使用。
• 源码版授权仅供购买者使用，禁止二次分发。

更新日志

见 changelog.md。