Yii2 项目接入阿里云短信,常见场景有注册验证码、登录验证、订单通知和安全提醒。代码里调用一次接口并不复杂,容易出问题的地方通常在前后环节:签名和模板是否审核通过、密钥如何保存、验证码怎样过期,以及发送失败后怎么处理。下面以 Yii2 高级版项目为例,把接入流程和上线检查逐项说明。
一、准备签名、模板和访问凭证
先在阿里云短信服务控制台完成基础配置,再开始写代码。发送请求需要使用已审核通过的签名名称和模板代码,不能随意填写或直接沿用未审核的模板。
- 短信签名:提交审核并通过后,记录签名名称。
- 短信模板:按业务创建模板,例如“您的验证码为${code},5分钟内有效”,通过审核后记录模板代码。
- 访问凭证:为服务端准备有短信发送权限的 RAM 用户凭证,权限尽量按实际用途收紧。
- 地域和接口信息:根据当前官方文档确认服务地域、接口版本及请求参数。
开发阶段可先用测试号码验证流程。不要为了方便把真实 AccessKey 写进代码,也不要将凭证提交到代码仓库。
二、用 Composer 安装 PHP SDK
在项目根目录按阿里云官方文档安装适用于短信服务的 PHP SDK。SDK 版本不同,依赖、命名空间和调用方式可能变化;安装后检查 composer.json 与锁文件是否都已更新,并在本地确认自动加载正常。
下面的服务代码只展示封装方式,客户端初始化和请求字段要按你安装的 SDK 版本补全。不要把旧版 SDK 的类名或参数直接套到新版示例中,否则常见结果是代码能运行到调用阶段,却因参数格式不符而失败。
三、在 Yii2 配置中读取环境变量
AccessKey ID 和 AccessKey Secret 应放在环境变量或部署平台的密钥管理功能中。Yii2 配置文件可以读取这些值,但文件本身不要保存真实凭证:
'sms' => [
'accessKeyId' => getenv('ALIYUN_ACCESS_KEY_ID'),
'accessKeySecret' => getenv('ALIYUN_ACCESS_KEY_SECRET'),
'signName' => getenv('ALIYUN_SMS_SIGN'),
'templateCode' => getenv('ALIYUN_SMS_TEMPLATE'),
],
再通过 Yii 的配置机制将参数交给短信服务。部署后要检查生产环境是否确实注入了这些变量;同时避免在日志、异常页面和调试输出中暴露密钥或验证码。
四、封装独立的短信发送服务
不要在多个控制器里重复初始化客户端、拼装请求。可以建立 SmsService,集中读取配置、调用 SDK 并处理响应。控制器只传手机号和业务参数,之后要增加日志、监控或更换短信渠道时,也不必逐个修改业务入口。
namespace app\services;
class SmsService
{
public function sendCode(string $phone, string $code): array
{
// 使用已安装版本的阿里云 SDK 创建客户端并发送请求
// 参数包括手机号、签名、模板代码及模板变量
// 按 SDK 响应统一返回成功或失败结果
return ['success' => false, 'message' => '请按 SDK 版本补充发送实现'];
}
}
实际代码应依据 SDK 返回的状态判断请求是否受理,并保留请求 ID 等排查信息。接口提示“请求已受理”,不代表用户手机已经收到短信;需要确认送达情况时,还要查看短信控制台回执或使用相应查询能力。
五、串起注册验证码的发送和校验
用户提交手机号后,服务端先校验格式,再检查手机号和 IP 的发送频率。通过检查后生成随机验证码,将验证码摘要、用途和过期时间写入缓存或数据库,再调用短信服务。只有发送请求成功受理,接口才返回“验证码已发送”。如果发送失败,应删除本次验证码记录,避免用户拿着未实际发送的验证码继续提交。
校验时,除了比对验证码,还要确认记录存在、未过期、未使用,并且手机号和业务场景一致。校验成功后立即标记为已使用,防止重复消费。验证码不宜长期明文保存,可存储哈希摘要并设置较短有效期。
六、按现象排查常见错误
- 签名或模板不匹配:核对控制台审核通过的签名名称、模板代码,以及模板变量名称和 JSON 格式。模板变量与代码中的字段对不上时,请求可能无法按预期发送。
- 鉴权失败:检查环境变量是否读取成功、RAM 用户是否具备所需权限、凭证是否有效,并确认地域和接口配置符合当前 SDK 文档。
- 接口返回成功但用户没收到:先看发送记录和回执,再检查号码状态、运营商拦截及模板内容。不要只凭接口返回就判断短信已送达。
- 本地正常、线上失败:确认生产环境配置已注入,服务器网络可以访问服务,并核对 PHP 扩展和依赖版本是否与本地一致。
- 短时间发送量异常:检查账户、签名、模板或号码维度是否触发限流。需要重试时按返回信息设置退避和次数上限,不要连续无间隔重复请求。
七、上线前检查风控和日志
短信验证码接口可能被批量调用。上线前应设置手机号、IP 和业务场景的频率限制,并结合业务情况增加图形验证或其他风险校验;每日发送总量和单个号码的发送次数也要有上限。调用失败时可以记录脱敏手机号、错误码和请求 ID,普通日志不要记录完整验证码或访问凭证。
例如,电商注册页刚接入短信时,如果只限制同一手机号的发送次数,攻击者仍可能换号码持续请求,消耗短信额度。此时可以补上 IP 限流、发送间隔、图形验证和异常告警,并为短信调用设置超时与有限重试。SDK 接通后,业务侧仍要持续检查发送量和异常情况。
完成 yii2 阿里云短信接入后,建议再走一遍完整流程:检查配置与模板、测试发送和验证码校验、确认失败时的处理方式,并验证限流和日志脱敏。把这些环节一起落实,短信功能才适合稳定用于注册、登录和通知。