更新记录

1.0.0（2026-04-11） 下载此版本

初次提交

平台兼容性

uni-app x(5.05)

laoqianjunzi-oauth

插件简介

laoqianjunzi-oauth 是一款面向 uni-app x 的本机身份校验插件，聚焦以下场景：

• 登录前二次确认
• 敏感操作解锁
• 进入隐私页面前身份复核
• 使用手机已录入的人脸、指纹或部分平台的系统口令完成验证

当前目录内已提供五端代码入口：

• app-android
• app-ios
• app-harmony
• mp-weixin
• web

其中：

• Android：支持系统生物识别，Android 10+ 可启用系统口令回退
• iOS：支持 Face ID、Touch ID，并可按配置启用系统口令回退
• Harmony：支持人脸、指纹、PIN 认证
• 微信小程序：支持 SOTER 指纹/面容能力
• Web：提供占位实现，保证跨端编译不报错

安装方法

将插件放入项目目录：

uni_modules/laoqianjunzi-oauth

页面中直接从插件根目录引入：

import {
  toggleOauthTrace,
  loadBiometricProfile,
  runOwnerValidation,
  OauthPromptConfig
} from "@/uni_modules/laoqianjunzi-oauth"

快速开始示例

import {
  toggleOauthTrace,
  loadBiometricProfile,
  runOwnerValidation,
  OauthPromptConfig
} from "@/uni_modules/laoqianjunzi-oauth"

const prompt : OauthPromptConfig = {
  panelTitle: '登录确认',
  panelSubtitle: '请完成设备认证',
  panelMessage: '验证通过后继续登录',
  fallbackMessage: '请使用系统口令完成校验',
  allowCredentialReuse: true
}

toggleOauthTrace(true)

loadBiometricProfile({
  success: (profile) => {
    console.log('认证概况', profile)
  }
})

runOwnerValidation({
  payload: prompt,
  success: (passed) => {
    console.log('是否通过', passed)
  },
  fail: (error) => {
    console.log(error.errCode, error.errMsg)
  }
})

完整 API 说明

toggleOauthTrace(enabled)

控制插件调试日志。

参数：

• enabled: boolean 是否输出调试信息

返回值：

• void

loadBiometricProfile(options)

异步读取当前设备的认证能力概况。

参数类型：OauthCapabilityOptions

type OauthCapabilityOptions = {
  success ?: (detail : OauthCapabilityResult) => void,
  fail ?: (detail : OauthBridgeFail) => void,
  complete ?: (detail : any) => void
}

返回结果：OauthCapabilityResult

type OauthCapabilityResult = {
  primaryMode : number,
  primaryModeName : string,
  supportsBiometric : boolean,
  supportsFace : boolean,
  supportsFingerprint : boolean,
  supportsPasscode : boolean,
  hasFaceEnrollment : boolean,
  hasFingerprintEnrollment : boolean,
  hasAnyEnrollment : boolean
}

primaryMode 说明：

• 1 指纹优先
• 2 面容优先
• 3 系统口令 / PIN
• 4 Optic ID
• -1 设备支持面容但未录入
• -2 设备支持指纹但未录入
• -3 当前设备不可用

runOwnerValidation(options)

拉起本机认证面板，完成一次身份验证。

参数类型：OauthAttemptOptions

type OauthPromptConfig = {
  panelTitle : string,
  panelSubtitle : string,
  panelMessage : string,
  fallbackMessage : string,
  allowCredentialReuse : boolean
}

type OauthAttemptOptions = {
  payload : OauthPromptConfig,
  success ?: (verified : boolean) => void,
  fail ?: (detail : OauthBridgeFail) => void,
  complete ?: (detail : any) => void
}

返回行为：

• success(true)：认证通过
• success(false)：面板仍在系统允许范围内，但本次识别未通过
• fail(...)：取消、锁定、不支持、未录入等中断型错误

错误码

各端注意事项

Android

• Android 9 及以上使用系统 BiometricPrompt
• Android 6 ~ 8 使用指纹能力兜底
• Android 10 及以上可通过 allowCredentialReuse 开启系统口令回退

iOS

• 首次启用 Face ID 需要系统弹出权限说明
• 插件已内置 NSFaceIDUsageDescription，如业务文案有要求，可自行调整 Info.plist
• 若 allowCredentialReuse = true，会使用 deviceOwnerAuthentication，允许系统口令回退

Harmony

• 优先接入人脸、指纹与 PIN
• allowCredentialReuse = true 时会启用系统复用解锁能力

微信小程序

• 依赖 SOTER 能力，仅支持微信宿主已开放的认证模式
• 小程序端不支持系统口令回退，allowCredentialReuse 参数会被忽略
• 认证能力查询为异步行为，请先调用 loadBiometricProfile

Web

• 当前实现为占位逻辑，仅用于保证跨端编译与调用安全
• 如需真正 WebAuthn 流程，建议在业务层单独实现 Web 方案，再与插件调用分流

常见问题

1. 为什么 success(false) 而不是 fail？

success(false) 表示系统面板已正常拉起，但这一次识别未通过，例如指纹不匹配。fail 只用于取消、锁定、未录入、不支持等中断型问题。

2. 为什么小程序端没有系统口令回退？

微信小程序的 SOTER 只暴露生物识别接口，不提供 App 侧那样的系统口令兜底能力，因此插件在该平台只保留面容 / 指纹验证。

3. Web 为什么会返回 9037107？

因为当前插件按 UTS 插件方式工作，Web 端没有统一的原生系统认证面板可直接复用，所以这里只保留占位实现，避免编译期与运行期异常。

4. 示例页面在哪里？

项目内已提供示例页：pages/oauth/index.uvue