Skip to Content
帮助文档行为配置操作指南发送和校验验证码

发送和校验验证码

验证码分两步完成:先用「发送验证码」行为向手机号或邮箱发出一个 6 位数字验证码,Zion 按 发送目标 + 使用场景 保存它;之后用户提交验证码时,再由注册、登录等系统行为自动校验,或在行为流中用「校验验证码」节点校验。

本文介绍三类常见需求:

  • 用内置场景完成注册、登录、重置密码等账号操作。
  • 用自定义场景,为自己的业务(如抽奖)加一道验证码校验。
  • 通过自定义渠道,用自己的短信或邮件服务发送验证码。

各行为和节点的逐项参数见参考手册:发送验证码、行为流节点。

基本概念

使用场景

使用场景说明这个验证码是做什么用的。发送和校验时选择的场景必须一致:用 register 场景发出的验证码,拿去登录会校验失败。

场景由系统枚举「验证码场景」定义,在 行为 → 验证码 → 使用场景 中管理。系统内置 6 个场景,名称为英文,每个场景由对应的行为自动校验:

场景用途由哪个行为校验
register手机号或邮箱注册注册
login手机号或邮箱验证码登录登录
reset通过手机号或邮箱重置密码重置密码
bind_account为当前账号绑定手机号或邮箱绑定
unbind_account为当前账号解绑手机号或邮箱解绑
delete注销当前账号注销

内置场景不能修改。业务需要其他用途时,可以新增 自定义场景,自定义场景需要在行为流中用「校验验证码」节点校验。场景名称只能包含英文字母、数字和下划线,且不能以数字开头,例如 lottery、withdraw_confirm。

发送渠道

渠道说明
系统短信由 Zion 发送,消耗项目的短信包数量
系统邮件由 Zion 发送
自定义渠道运行你配置的行为流,由你接入的服务商发送,见接入自有短信 / 邮件服务

验证码规则

规则说明
格式与有效期6 位数字,5 分钟内有效
场景一致发送和校验的场景、发送目标都必须一致
重新发送同一目标、同一场景重新发送后,之前的验证码立即失效
一次性使用校验成功后验证码立即作废,不能重复使用
发送间隔使用系统短信或系统邮件时,同一目标、同一场景 1 分钟内只能发送一次;不同场景分别计算

在 行为 → 验证码 中修改使用场景或发送渠道后,需要同步后端才会生效。

用内置场景:手机号验证码登录

以 Web 应用的手机号验证码登录为例。

开启登录方式

打开顶部的 行为,进入 登录,在 登录方式选择 中开启 手机号验证码。使用邮箱验证码时开启 邮箱验证码。

未开启对应登录方式时,发送验证码会失败。

发送验证码

在「获取验证码」按钮的点击事件中添加 通讯 → 发送验证码 行为:

配置项设置
发送渠道系统短信
使用场景login
发送给手机号输入框的值

建议为按钮加上 60 秒倒计时,避免用户在发送间隔内重复点击,做法见Web 应用验证码倒计时。

登录并校验

在「登录」按钮的点击事件中添加 登录 行为,方式选择 手机号验证码登录,手机号和验证码分别绑定对应输入框的值。

登录行为会自动用 login 场景校验验证码,校验通过后登录成功,进入 成功时 分支;验证码错误或已过期时进入 失败时 分支,可以在这里提示用户重新获取验证码。

其他内置场景的配置方式相同,只需换成对应的场景和行为:

需求发送验证码的场景校验的行为
手机号或邮箱注册register注册
忘记密码reset重置密码
绑定手机号或邮箱bind_account绑定
解绑手机号或邮箱unbind_account解绑
注销账号delete注销

选择 delete 场景时不需要填写 发送给,系统会把验证码发送到当前登录用户已绑定的手机号或邮箱。

用自定义场景:抽奖前短信验证

以抽奖为例:已登录用户点击「立即抽奖」前,需要输入发到自己手机上的验证码,用来拦截脚本刷抽奖。

新增场景

打开顶部的 行为,进入 验证码,在 使用场景 表格末行点击 新增场景,命名为 lottery,然后同步后端。

发送验证码

在「获取验证码」按钮的点击事件中添加 通讯 → 发送验证码 行为:

配置项设置
发送渠道系统短信
使用场景lottery
发送给当前用户的手机号

使用系统短信发送时,同样需要在 行为 → 登录 中开启 手机号验证码。

在行为流中校验并抽奖

新建一个同步行为流「抽奖」,添加文本入参「验证码」,然后依次添加节点:

  1. 当前用户 - 获取账户 ID:获取当前用户 ID。
  2. 数据库 - 获取数据:选择账户表进行查询,以用户 ID 为过滤条件,取出该用户的手机号。
  3. 通讯 - 校验验证码:scenario 选择 lottery,sendTo 绑定上一步查到的手机号,code 绑定入参「验证码」。
  4. 条件分支:判断校验验证码节点的输出 valid。
    • valid 为 false:添加 抛出异常 节点,错误信息填写「验证码错误或已过期」。
    • valid 为 true:继续执行抽奖逻辑。
  5. 抽奖逻辑:查询奖池、随机抽取并写入中奖记录,最后通过出参返回中奖结果。
⚠️

校验验证码节点校验失败时不会报错,只会输出 valid 为 false。如果后面不判断 valid,抽奖逻辑会照常执行。

⚠️

手机号要在行为流中通过当前用户查询,不要由页面作为入参传入。否则用户可以填自己能收到短信的其他手机号,绕过对当前账号的验证。

⚠️

抽奖逻辑必须放在校验节点之后、同一个行为流中。如果先单独校验、再由前端根据结果调用另一个抽奖行为流,抽奖行为流可以被直接调用,校验就失去了意义。

在页面中调用行为流

在「立即抽奖」按钮的点击事件中添加运行行为流,选择「抽奖」,入参「验证码」绑定验证码输入框的值。在 成功时 分支展示中奖结果,在 失败时 分支提示失败原因。

验证码只能确认操作者能收到这个手机号的短信,不能限制抽奖次数。每人每天可抽几次等规则,需要在抽奖逻辑中另行判断。

不要用校验验证码节点去校验内置场景的验证码。节点校验成功后验证码就会作废,之后注册、登录等行为再校验同一个验证码会失败。

接入自有短信 / 邮件服务

不想使用系统短信、或需要自定义短信签名和模板时,可以添加自定义渠道,用你自己的服务商(如阿里云、腾讯云、Twilio)发送验证码。自定义渠道本质上是一个行为流:发送验证码时,Zion 生成验证码后运行这个行为流,由行为流负责把验证码发出去。

创建发送行为流

新建行为流,添加 3 个文本入参:接收账号、验证码、场景。

在行为流中添加发送节点,例如 发送短信 - 阿里云、发送短信 - Twilio、发送邮件 - 阿里云,或通过 API 调用其他服务商,并把入参绑定到节点的接收方和内容上。

「场景」入参收到的是场景名称(如内置的 register、login,或你新增的 lottery),可以用它为不同场景选择不同的短信模板。

添加自定义渠道

打开顶部的 行为,进入 验证码,在 发送渠道 表格末行新增渠道:

字段说明
名称渠道名称,会显示在发送验证码行为的发送渠道下拉中,如「腾讯云短信」
方式短信或邮箱
发送验证码的行为流选择上一步创建的行为流
行为流输入在数据绑定菜单的「上下文 - 验证码」分类下,把 发送目标、验证码、场景 分别绑定到行为流的接收账号、验证码、场景入参

保存后同步后端。如果当前套餐不支持自定义渠道,页面会显示升级提示。

在发送验证码中选择渠道

在发送验证码行为的 发送渠道 中,从 自定义 分组里选择刚添加的渠道。校验方式不变,仍由对应的系统行为或校验验证码节点完成。

如果发送行为流设置为异步执行,发送验证码行为在行为流开始运行后就会返回成功,行为流中的发送失败不会反馈到页面上。需要页面感知发送失败时,请使用同步执行。

小程序注意事项

微信小程序的发送验证码行为只支持 bind_account、unbind_account 和自定义场景。

从「默认」场景迁移

旧版小程序的发送验证码行为有一个「默认」场景,新版中已经被移除。

原来已经配置了默认场景的行为,配置保留,线上正常运行,但无法编辑。建议按以下步骤,把这类配置改为自定义场景加行为流校验:

新增自定义场景

在 行为 → 验证码 → 使用场景 中,按业务用途新增场景,例如 coupon,然后同步后端。原来有多处用「默认」场景做不同业务的,可以分别新增场景。

修改发送验证码行为

找到原来使用「默认」场景的发送验证码行为,把 使用场景 改为刚新增的场景,发送渠道和发送给保持不变。

把校验和业务操作移到行为流

新建一个同步行为流,入参为手机号和验证码(手机号如果已绑定在账号上,也可以在行为流中按当前用户查询),然后依次添加:

  1. 通讯 → 校验验证码:scenario 选择新增的场景,sendTo 绑定手机号,code 绑定验证码。
  2. 条件分支:valid 为 false 时用 抛出异常 中断;为 true 时继续。
  3. 原来放在前端「校验验证码」成功时 分支中的业务操作,例如领券的数据库写入,改为在这里用行为流节点完成。

替换前端的校验验证码行为

在页面中删除原来的前端「校验验证码」行为,改为运行上一步的行为流。原来 成功时 / 失败时 分支里的提示、跳转等界面操作,移到运行行为流的 成功时 / 失败时 分支中。

⚠️

发送验证码行为和校验方式要一起修改。发送验证码改用新场景后,前端「校验验证码」行为就校验不到新发出的验证码,用户输入正确也会失败。

常见问题

  1. 验证码输入正确,但校验失败:依次检查:
    • 发送和校验选择的场景是否一致。
    • 用户是否又点了一次获取验证码。重新发送后,之前的验证码会失效。
    • 是否已超过 5 分钟有效期。
    • 验证码是否已经被使用过一次,例如被校验验证码节点提前校验过。
    • 发送和校验时的手机号或邮箱是否一致。
  2. 提示发送过于频繁:使用系统短信或系统邮件时,同一目标、同一场景 1 分钟内只能发送一次;系统短信还受短信服务商的发送上限约束,同一手机号每分钟最多 2 条、每小时最多 10 条、每天最多 10 条。
  3. 发送验证码一直失败:检查 行为 → 登录 中是否开启了对应的 手机号验证码 或 邮箱验证码。
  4. 修改场景或渠道后没有生效:在 行为 → 验证码 中修改后需要同步后端。
  5. 重命名或删除自定义场景后出错:已经引用该场景的发送验证码行为和校验验证码节点需要一并检查。删除已部署的场景时,编辑器会先要求确认。
  6. 注销账号的验证码发给了谁:发送到当前登录用户已绑定的手机号(短信渠道)或邮箱(邮件渠道)。
Last updated on