ThinkPHP6.x短信验证码应选用轻量SDK、配置与密钥分离、严格遵循平台参数命名、强制捕获全类型异常并记录、独立管控验证码生命周期。
如果您在ThinkPHP6.x项目中需实现短信验证码功能，但调用第三方平台时频繁出现发送失败、异常静默、签名模板报错或鉴权拒绝等问题，则很可能是SDK选型、配置方式或异常处理机制不符合平台实际要求。以下是针对主流平台的可落地、经验证的最佳实践方案：
一、选用轻量级SDK替代全量包
阿里云与腾讯云官方全量SDK存在强依赖（如Guzzle 7+、PSR-18新标准），而ThinkPHP6.x默认锁定Guzzle 6.x且自动加载机制不兼容，直接composer require alibabacloud/sdk或tencentcloud/tencentcloud-sdk-php-all极易引发类未找到、方法不存在或HTTP客户端冲突。必须改用精简、可控的通信层封装。
1、阿里云场景下执行：composer require alibabacloud/pop-core，该包体积仅约30KB，无Guzzle硬依赖，仅需原生cURL支持。
2、腾讯云场景下执行：composer require tencentcloud/tencentcloud-sdk-php（注意末尾无-all），避免引入COS、CKafka等无关模块。
立即学习“PHP免费学习笔记（深入）”；
3、手动创建app/service/SmsService.php，禁止将SDK初始化逻辑写入vendor或覆盖AlibabaCloud\Client默认实例。
二、配置与密钥严格分离
敏感凭证不得硬编码于服务类中，否则易导致Git泄露或测试环境误用生产密钥。所有参数须统一收口至config/sms.php，并通过框架配置系统动态注入，确保开发、测试、生产三环境隔离。
1、在config/sms.php中定义结构化配置：
return [
'default' => 'aliyun',
'drivers' => [
'aliyun' => [
'access_key_id' => env('SMS_ALIYUN_ACCESS_KEY_ID', ''),
'access_key_secret' => env('SMS_ALIYUN_ACCESS_KEY_SECRET', ''),
'region_id' => 'cn-hangzhou',
'sign_name' => env('SMS_ALIYUN_SIGN_NAME', ''),
'template_code' => env('SMS_ALIYUN_TEMPLATE_CODE', ''),
],
'tencent' => [
'secret_id' => env('SMS_TENCENT_SECRET_ID', ''),
'secret_key' => env('SMS_TENCENT_SECRET_KEY', ''),
'region' => 'ap-guangzhou',
'sdk_app_id' => env('SMS_TENCENT_SDK_APP_ID', ''),
'sign_name' => env('SMS_TENCENT_SIGN_NAME', ''),
'template_id' => env('SMS_TENCENT_TEMPLATE_ID', ''),
],
],
];
2、通过Env文件管理各环境密钥，严禁在代码中明文出现AccessKeyId、SecretKey、SdkAppId等值。
3、签名与模板ID必须已在对应平台控制台完成人工审核，否则调用必返回InvalidParameter.SignName或TemplateNotFound。
三、构造请求参数完全遵循平台文档字段名
腾讯云与阿里云对参数命名、类型、嵌套层级有严格校验，任意偏差（如大小写、下划线/驼峰、数组键名拼写）均会导致400或InvalidParameterValue错误，而非业务逻辑错误提示。
1、阿里云SendSms接口必须使用以下精确字段名：
- PhoneNumbers（非phone_number或mobile）
- SignName（非signname或sign）
- TemplateCode（非template_id或tpl_code）
- TemplateParam（JSON字符串格式，如{"code":"1234"}，非关联数组）
2、腾讯云SendSms接口必须使用以下精确字段名：
- PhoneNumberSet（数组，元素为+8613800138000格式，含国家码）
- SdkAppId（字符串，非sdkappid或app_id）
- TemplateId（字符串，非template_code）
- TemplateParamSet（字符串数组，顺序必须与模板变量一一对应，错一位即InvalidParameterValue.TemplateParameterFormatError）
3、腾讯云region参数必须传完整字符串如"ap-guangzhou"，不可省略"ap-"前缀。
四、强制捕获全类型异常并记录原始错误
ThinkPHP6默认异常处理器会拦截SDK抛出的底层网络异常（如GuzzleHttp\Exception\RequestException、TencentCloudSDKException），转为500页面，导致开发者无法看到真实错误原因（如DNS失败、SSL证书过期、401 Unauthorized）。必须在SmsService发送方法内显式覆盖所有可能异常分支。
1、在发送方法中使用catch (\Exception $e)兜底，而非仅捕获特定SDK异常类。
2、记录完整错误上下文：Log::error('SMS send failed: ' . $e->getMessage() . ', code: ' . $e->getCode() . ', trace: ' . $e->getTraceAsString())。
3、对腾讯云401错误，立即检查Credential构造是否同时传入secretId和secretKey；对阿里云Forbidden.RAM错误，确认RAM子账号已授予AliyunDysmsReadOnlyAccess或自定义策略含dysms:SendSms权限。
4、禁止依赖SDK文档中“成功返回JSON”的假设，必须预设网络层失败为常态。
五、验证码生命周期管控必须独立于短信通道
短信发送成功不等于用户收到或输入正确，验证码有效性、频控、防刷必须由应用层自主实现，不可交由第三方平台代管。
1、生成6位随机码后，立即存入Redis，键名为sms:code:{phone}，过期时间设为180秒（3分钟），值为纯数字字符串。
2、发送前校验同一手机号60秒内发送次数是否≤1次，使用cache('sms:count:{phone}', 0, 60)递增计数器。
3、单日发送上限设为5次，使用cache('sms:day:{phone}', 0, 86400)维护当日累计值。
4、校验验证码时，先GET再DEL，确保一次性使用，防止重放攻击。
