更新记录

1.0.0(2026-11-19) 下载此版本

初始化项目


平台兼容性

云端兼容性

支付宝云 腾讯云 阿里云
× × √

uni-id 3.3.34 使用说明

对象:uni-id_3.3.34_example.zip(uniCloud 用户中心模板 / uni-id 官方示例) 适用:uniCloud 阿里云版、uni-app(Vue2 写法,非 uni-app x) 本文按包内实际代码写成,不是照抄 README。


1. 这个包是什么

一套可直接跑通的 uni-id 全功能演示工程:客户端 9 个页面 + 1 个聚合云函数 uni-id-test + 3 个公共模块 + 4 张表的初始化配置。登录方式覆盖用户名密码、手机验证码、邮箱验证码、微信 / QQ / 支付宝,另含绑定解绑、邀请码、角色权限(RBAC)。

组成 路径 说明
客户端页面 pages/ 9 页,每页对应一组接口
云函数 uniCloud-aliyun/cloudfunctions/uni-id-test/ 单文件 37 个 action 的聚合入口
核心公共模块 uni_modules/uni-id/ v3.3.34,uniCloud/cloudfunctions/common/uni-id
配置中心 uni_modules/uni-config-center/ v0.0.2,uni-id 从此读 config.json
三方凭证托管 uni_modules/uni-open-bridge-common/ v1.0.3,3.3.29 起用于存三方 access_token
建表脚本 uniCloud-aliyun/database/db_init.json 4 张空表

它不是生产模板:页面里大量参数(验证码、密码、uid)写在客户端,包内首页自己也挂了红字提示。生产必须把参数判定挪进云函数。


2. 前置条件

  • HBuilderX(含 uniCloud 插件),登录 DCloud 账号
  • 一个 uniCloud 服务空间(阿里云版;本包目录名是 uniCloud-aliyun,腾讯云版需改为 uniCloud-tcb 并重新初始化)
  • 服务空间已开通短信服务(要用手机验证码时)与相应实名 / 额度
  • 三方登录需自备开放平台资质:微信开放平台 / QQ 互联 / 支付宝开放平台

3. 五步部署(按代码依赖顺序,别跳步)

步骤 1:关联服务空间

HBuilderX 里右键项目根 →「创建 / 关联 uniCloud 服务空间」,选中目标空间。关联后 uniCloud-aliyun 目录才会出现上传菜单。

步骤 2:改配置(config.json)

路径:uni_modules/uni-config-center/uniCloud/cloudfunctions/common/uni-config-center/uni-id/config.json

{
  "passwordSecret": "passwordSecret-demo",   // ← 必改,密码加盐
  "tokenSecret": "tokenSecret-demo",         // ← 必改,token 签名
  "tokenExpiresIn": 7200,
  "tokenExpiresThreshold": 600,
  "passwordErrorLimit": 6,
  "passwordErrorRetryTime": 3600
}

⚠️ 这 5 项(passwordSecret / tokenSecret / tokenExpiresIn / passwordErrorLimit / passwordErrorRetryTime)缺失时 uni-id 直接抛 config-param-required,服务起不来。 ⚠️ 两个 secret 上线前必须换成随机长串。改 passwordSecret 会让存量密码全部失效,改 tokenSecret 会让存量 token 全部失效——上线后再改等于强制全员重新登录。

各端三方登录按需填(不用就留占位):

端 配置节点 必填
App app-plus.oauth.weixin appid、appsecret
App(苹果) app-plus.oauth.apple bundleId
App(QQ) app-plus.oauth.qq appid、appsecret
微信小程序 mp-weixin.oauth.weixin appid、appsecret
支付宝小程序 mp-alipay.oauth.alipay appid、privateKey
QQ 小程序 mp-qq.oauth.qq appid、appsecret
短信 service.sms name: "DCloud"、smsKey、smsSecret、codeExpiresIn
一键登录 service.univerify appid、apiKey、apiSecret

步骤 3:初始化数据库

右键 uniCloud-aliyun/database/db_init.json →「初始化云数据库」。会建 4 张空表:

集合 存什么
uni-id-users 用户(含 password、mobile、email、role、permission、invite_code…)
uni-id-roles 角色定义
uni-id-permissions 权限点定义
opendb-verify-codes 短信 / 邮箱验证码,带过期时间

步骤 4:上传公共模块(必须先于云函数)

在 uniCloud-aliyun/cloudfunctions/common/ 上右键 →「上传公共模块」,勾选:

  • uni-id
  • uni-config-center
  • uni-open-bridge-common(要用三方登录才需要,但建议一起传)

或在 uni_modules 对应插件上右键「上传公共模块」。顺序错了云函数会报 Cannot find module 'uni-id' 或 uni-id config file[...] not found。

步骤 5:上传云函数

右键 uniCloud-aliyun/cloudfunctions/uni-id-test →「上传部署」。

package.json 里依赖已写成相对路径:

"dependencies": {
  "uni-id": "file:../../../uni_modules/uni-id/uniCloud/cloudfunctions/common/uni-id"
}

HBuilderX 会按此打包。若上传后运行报找不到模块,右键云函数 →「管理公共模块依赖」→ 勾选 uni-id、uni-config-center 再传一次。

收尾:跑起来

HBuilderX 运行到浏览器 / 微信开发者工具 / 真机。首页按平台条件编译显示入口:微信(App + 微信小程序)、QQ(App + QQ 小程序)、支付宝(仅支付宝小程序)。


4. 统一调用协议

所有功能都走同一个云函数、同一个信封:

uniCloud.callFunction({
  name: 'uni-id-test',
  data: {
    action: 'login',                    // 必填,决定走哪个分支
    params: { username, password },     // 业务参数
    uniIdToken: 'xxx'                   // 受保护 action 必填(顶层字段,不是放在 params 里)
  }
})

返回:

{ code: 0, token, tokenExpired, ... }     // 成功
{ code: 'password-error', errMsg: '...' } // 失败:3.x 起 code 可能是字符串 errCode
{ code: 403, msg: '缺少token' }            // 云函数自己拦的
{ code: 404, msg: 'NOT_FOUND' }            // action 不存在

判断成功用 code === 0,不要用 code > 0(字符串 errCode 会让 > 0 永远为 false)。

云函数 URL 化(可选)

index.js 顶部已注明:URL 化后 GET 的参数在 event.queryStringParameters,POST 在 event.body(字符串,需自行 JSON.parse),而本函数只读 event.action / event.params / event.uniIdToken。要对外开放必须先补一层参数归一化。


5. 鉴权是怎么走的(index.js 逻辑)

event.action 在白名单?
├─ 是 → 直接进 switch(不校验 token)
└─ 否 → event.uniIdToken 为空?
        ├─ 是 → return { code: 403, msg: '缺少token' }
        └─ 否 → payload = checkToken(uniIdToken, { needPermission: true })
                ├─ 失败 → 原样返回 payload
                └─ 成功 → params.uid = payload.uid   ← 服务端注入,客户端别自己传 uid

白名单(noCheckAction)实际是:

['register', 'checkToken', 'encryptPwd', 'login', 'loginByWeixin', 'loginByQQ',
 'sendSmsCode', 'setVerifyCode', 'loginBySms', 'loginByEmail',
 'code2SessionWeixin', 'code2SessionAlipay']

三个容易踩的点:

  1. checkToken 在白名单里,但仍然要传 uniIdToken —— 分支内部是 uniID.checkToken(event.uniIdToken),不传就报错。
  2. loginByAlipay 不在白名单 —— 支付宝小程序登录会直接 403。要跑通就在数组里补 'loginByAlipay'。
  3. encryptPwd 在白名单里 —— 任何人都能调加密接口,生产必须移出白名单。

6. Action 速查(37 个)

"需 token"列指必须传顶层 uniIdToken。

6.1 账号与密码

action 需 token 关键参数 说明
register 否 username、password、needPermission 注册,成功直接返回 token
login 否 username、password、needPermission 默认只查 username;本函数已传 queryField: ['username','email','mobile'],三者任一都能登
logout 是 — 使当前 token 失效
updatePwd 是 oldPassword、newPassword uid 由服务端注入
resetPwd 是 — 演示用:把当前用户密码重置为写死的 123456
encryptPwd 否 — 返回 123456 的加密结果,仅供调试
checkToken 是(见上) — 校验并可能续签 token;3.0 起不再返回用户信息
updateUser 是 nickname 等 更新用户资料
setAvatar 是 avatar 设置头像 URL

6.2 手机号 / 邮箱 / 验证码

action 需 token 关键参数 说明
sendSmsCode 否 mobile、type、templateId 发短信验证码。type:login / register / bind / unbind
setVerifyCode 否 mobile 或 email、code、type 自建短信通道时自己写码,语义同 sendSmsCode
loginBySms 否 mobile、code、type? 不传 type = 存在则登录、不存在则注册
loginByEmail 否 email、code 同上,邮箱版
bindMobile 是 mobile、code? 不传 code 直接绑定并置 mobile_confirmed=1
unbindMobile 是 mobile、code? 不传 code 直接解绑
bindEmail 是 email、code? 不传 code 直接绑定
unbindEmail 是 email、code? 不传 code 直接解绑

⚠️ sendSmsCode 分支里 templateId 当前是空字符串,代码会直接 throw:必须先去 uniCloud 控制台申请短信模板,把模板 ID 填进 index.js 的 const templateId = '' 处,否则手机验证码链路一步都走不通。 ⚠️ 演示页把验证码生成放在了客户端(getCode() 随机 6 位),sendSmsCode 还把客户端生成的 code 传给云端——生产环境必须由云端生成(官方推荐 sendSmsCode 不传 code)。

6.3 三方登录(微信 / QQ / 支付宝)

action 需 token 关键参数
code2SessionWeixin 否 code(只换 openid,不建号)
loginByWeixin 否 code
bindWeixin 是 code
unbindWeixin 是 —
loginByQQ 否 code、accessToken
bindQQ 是 code、accessToken
unbindQQ 是 —
code2SessionAlipay 否 code
loginByAlipay 是(白名单缺失) code
bindAlipay 是 code
unbindAlipay 是 —

客户端拿 code 的方式(pages/weixin 已实现):App 端 plus.oauth.getServices → authorize 取 code;微信小程序 uni.login({ provider: 'weixin' })。

6.4 邀请码

action 需 token 关键参数 说明
setUserInviteCode 是 — 不传则随机生成 6 位
acceptInvite 是 inviteCode 接受他人邀请

是否强制邀请码由配置控制:autoSetInviteCode(注册时自动生成)、forceInviteCode(注册必须填)。

6.5 角色权限(RBAC)

action 需 token 关键参数
addRole 是 roleID、roleName、comment、permission
getRoleList 是 offset、limit、needTotal
addPermission 是 permissionID、permissionName、comment
getPermissionList 是 offset、limit、needTotal
getRoleByUid 是 —(uid 服务端注入)
bindRole 是 roleList、reset(true 覆盖 / false 增量)
bindPermission 是 roleID、permissionList、reset

pages/rbac 里可直接试:建权限 → 建角色 → 给用户绑角色 → 给角色绑权限。


7. 客户端接入(从 demo 到能用的最小改造)

7.1 demo 的致命简化

9 个页面没有一个传 uniIdToken。 结果:除了白名单 action,点按钮一律 403 缺少token——updatePwd、logout、bindMobile、setAvatar、getRoleList、邀请码全套都跑不通。

这不是你配错了,是 demo 只演示 action 分发。把 token 补上即可。

7.2 建议的调用封装

// utils/uni-id.js
const CF = 'uni-id-test'

function callId(action, params = {}) {
  const token = uni.getStorageSync('uni_id_token')
  const data = { action, params }
  if (token) data.uniIdToken = token          // 顶层字段
  return uniCloud.callFunction({ name: CF, data }).then((res) => {
    const r = res.result
    if (r.code !== 0) return Promise.reject(r)
    // 登录类接口会带回新 token,统一落盘 + 续期
    if (r.token) {
      uni.setStorageSync('uni_id_token', r.token)
      uni.setStorageSync('uni_id_token_expired', r.tokenExpired)
    }
    return r
  })
}

export const login = (username, password) => callId('login', { username, password })
export const getRoleList = () => callId('getRoleList', { offset: 0, limit: 20, needTotal: true })

要点:

  • uniIdToken 放顶层,放 params 里不生效;
  • token 与 tokenExpired 成对存储(demo 用的 key 就是 uni_id_token / uni_id_token_expired);
  • 每次调用都可能续签,只要返回里有 token 就覆盖存(tokenExpiresThreshold 控制续签时机)。

7.3 生产必须做的三件事

  1. 参数判定搬进云函数:密码规则、验证码、needPermission 不能由客户端决定(params.uid 已由服务端注入,客户端传了也会被覆盖,但其它字段没有这层保护)。
  2. 别把 event 全量透传:本函数逐个字段解构是有意为之,别改成 uniID.login(event.params)。
  3. 加频率限制:sendSmsCode、login、register 至少按 IP / mobile 限流,短信是按条计费的。

8. 配置项详解

配置 默认/示例 作用
passwordSecret 必填 密码加盐。改了就全员密码失效
tokenSecret 必填 token 签名密钥。改了就全员 token 失效
tokenExpiresIn 7200 token 有效期(秒)。app-plus 节点下示例为 2592000(30 天)
tokenExpiresThreshold 600 剩余有效期低于此值时 checkToken 自动续签并返回新 token
passwordErrorLimit 6 连续密码错误次数上限
passwordErrorRetryTime 3600 触发上限后的锁定时长(秒)
autoSetInviteCode false 注册时自动生成邀请码
forceInviteCode false 注册必须填邀请码
removePermissionAndRoleFromToken 未配置(=缓存) true 时不在 token 内缓存角色权限,每次查库

平台级覆盖:app-plus / mp-weixin / mp-alipay / mp-qq 节点下的 tokenExpiresIn、oauth 会按当前端覆盖顶层值。一套代码多端发布时,注意 _getConfig 用 APPID_PLATFORM 做缓存 key——同一服务空间挂多个 appid 时配置要按 appid 分组(数组形式)。


9. 角色权限在 token 里的坑

3.0.0 起默认把 role / permission 缓存进 token:

  • 好处:checkToken 不查库就能返回权限,省读次数、响应快;
  • 代价:权限改了、token 没到期,用户仍是旧权限。缓解办法是把 tokenExpiresIn 调短,或配 removePermissionAndRoleFromToken: true 回到查库模式;
  • admin 角色 token 内不含 permission。判断权限要写成:
const { role, permission } = await uniID.checkToken(event.uniIdToken)
if (role.includes('admin') || permission.includes('your-permission-id')) {
  // 有权限
}

另外:pages/rbac 顶部提示「登录时传 needPermission: true,checkToken 才返回 Permission」是旧版语义。3.x 缓存开启后该参数不再生效(README 已明确说明),要关闭缓存只能用 removePermissionAndRoleFromToken。


10. 常见问题

现象 原因 / 处理
所有受保护接口返回 403 缺少token demo 页面不传 token。按 7.2 补 data.uniIdToken
上传云函数报 Cannot find module 'uni-id' 公共模块没传或没勾依赖。先传 uni-id + uni-config-center,再「管理公共模块依赖」重传
报 uni-id config file[...] not found uni-config-center 没上传,或 config.json 路径不对(必须在 common/uni-config-center/uni-id/config.json)
启动报 config-param-required 5 个必填项缺了,见第 3 步
发短信直接抛 templateId 错误 index.js 里 templateId 为空,去控制台申请模板后填上
微信 / QQ 登录报 get-third-party-account-failed / get-third-party-user-info-failed oauth 的 appid / appsecret 没填或与当前端不匹配(App 用 app-plus.oauth,小程序用 mp-*.oauth)
支付宝小程序登录 403 loginByAlipay 不在 noCheckAction,补进白名单
重置密码后登不上 resetPwd 把密码写死成 123456,这是演示逻辑
换 passwordSecret 后老用户登不上 预期行为:盐变了,旧 hash 校验不过
本地跑通、真机不行 真机需重新关联服务空间并上传;检查是否用了另一个空间
uni-open-bridge 报集合不存在 用三方登录时会把凭证写入 opendb-open-data,把插件内 uniCloud/database/opendb-open-data.schema.json 上传建表

包内已知不一致(照做会卡住)

位置 说法 实际
根 README.md 第 4~5 步 在云函数 user-center 下安装 uni-id 并上传 包内云函数叫 uni-id-test,没有 user-center
README.md 第 1 步 在公用模块 uni-id 的 config.json 内配置 配置文件实际在 uni-config-center/.../uni-id/config.json
pages/rbac 提示 needPermission: true 才返回 Permission 3.x 缓存角色权限后该参数不再生效
index.js 白名单 不含 loginByAlipay 支付宝登录会 403
index.js 校验 if (payload.code && payload.code > 0) 字符串 errCode 时判不成立,建议 payload.code !== 0

11. 生产上线清单

  • [ ] passwordSecret / tokenSecret 换成随机长串,且不进 Git
  • [ ] 删除或移出白名单:encryptPwd;补入:loginByAlipay
  • [ ] 删掉 resetPwd 的写死密码分支(或改为走 resetPwdBySms)
  • [ ] 验证码改由云端生成,客户端不再传 code
  • [ ] sendSmsCode / login / register 加限流与图形验证
  • [ ] 客户端只存 token,不存密码;tokenExpired 到期前主动续签
  • [ ] 权限判断统一按「role.includes('admin') 或 permission.includes(pid)」
  • [ ] 三方 appsecret 只放云端配置,不打进客户端包
  • [ ] 云函数 URL 化时补 queryStringParameters / body 的归一化,并加签名校验

12. 附:文件清单与版本

文件 作用
uniCloud-aliyun/cloudfunctions/uni-id-test/index.js 37 个 action 的聚合入口(439 行)
uniCloud-aliyun/database/db_init.json 4 张表初始化
uni_modules/uni-id/ v3.3.34(2025-08-25,修多语言错误文案)
uni_modules/uni-config-center/ v0.0.2
uni_modules/uni-open-bridge-common/ v1.0.3(3.3.29 起托管三方凭证)
pages/{index,password,mobile,email,weixin,qq,alipay,util,rbac}/ 9 个演示页

版本脉络(3.3.x 关键节点)

  • 3.3.29 三方凭证改由 uni-open-bridge-common 托管
  • 3.3.30 短信、一键登录密钥改为非必填
  • 3.3.32 兼容 uni-app x 的 uniPlatform(app-android / app-ios 拆分)
  • 3.3.34 修部分错误信息多语言配置

官方文档:https://doc.dcloud.net.cn/uniCloud/uni-id/old.html

(注:部分内容由豆包 AI 生成)

隐私、权限声明

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

无

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

无

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

无

许可协议

MIT协议

暂无用户评论。