更新记录
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-iduni-config-centeruni-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']
三个容易踩的点:
checkToken在白名单里,但仍然要传uniIdToken—— 分支内部是uniID.checkToken(event.uniIdToken),不传就报错。loginByAlipay不在白名单 —— 支付宝小程序登录会直接 403。要跑通就在数组里补'loginByAlipay'。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 生产必须做的三件事
- 参数判定搬进云函数:密码规则、验证码、
needPermission不能由客户端决定(params.uid已由服务端注入,客户端传了也会被覆盖,但其它字段没有这层保护)。 - 别把
event全量透传:本函数逐个字段解构是有意为之,别改成uniID.login(event.params)。 - 加频率限制:
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 生成)

收藏人数:
下载插件并导入HBuilderX
赞赏(0)
下载 0
赞赏 0
下载 35312
赞赏 159
赞赏
京公网安备:11010802035340号