应只引入最小必要模块：go get github.com/tencentcloud/tencentcloud-sdk-go@v1.0.725，并显式导入短信及配套公共模块，避免全量引入导致版本冲突和 import cycle 错误。
腾讯云短信 SDK 的 go.mod 依赖怎么加才不冲突
直接 go get github.com/tencentcloud/tencentcloud-sdk-go 很容易和项目里已有的 github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile 或其他子包版本不一致，尤其当项目用了 viper 或 gin 的中间件链时，会报 cannot load package: import cycle not allowed 或 undefined: tencentcloud.NewClient 这类错误。
正确做法是只引入最小必要模块：
- 用
go get github.com/tencentcloud/tencentcloud-sdk-go@v1.0.725（截至 2026 年 8 月最新稳定版） - 不 import 全量 SDK，只 import 短信模块：
github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/sms/v20210111 - 配套的公共模块必须显式指定：
github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common和github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common/profile - 如果项目已用
viper加载配置，确保SmsOptions结构体字段名与 YAML 键完全一致（比如secret-id对应 struct tagmapstructure:"secret-id"），否则viper.UnmarshalKey("sms", &opts)会静默失败
发送验证码前，手机号和模板参数怎么校验才不被腾讯云拒掉
腾讯云 SMS 接口对 mobile 和 template-id 校验极严，不是格式对就行——它会检查号码归属地、模板是否已审核通过、签名是否绑定该模板、模板变量是否匹配实际传入值。常见错误是返回 FailedOperation.TemplateParameterError 或 AuthFailure.SignatureFailure。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
-
mobile必须带国家码，国内号码写成+8613812345678，不能是13812345678或013812345678 -
TemplateId必须是控制台「已审核通过」状态的 ID，草稿或待审核状态会直接返回InvalidParameterValue.TemplateId - 模板内容含变量（如
{1}）时，TemplateParamSet数组长度必须严格等于模板中变量个数，且每个元素为字符串，空值要传" "而非""或nil - 签名（
SignName）必须和模板在控制台完成「签名-模板」绑定，否则报AuthFailure.SignatureFailure，这个绑定操作不能跳过
gin handler 里调用短信接口，为什么总是超时或 panic
直接在 c.POST("/send-code", ...) 里同步调用腾讯云 SDK，容易因网络抖动、DNS 解析慢、SDK 内部重试逻辑卡住整个 HTTP 请求协程，导致 gin 返回 504 Gateway Timeout 或 goroutine 泄漏。
关键处理点：
- 给 SDK client 显式设置超时：
profile.WithHttpTransport(&http.Transport{...})，其中Timeout设为 5s，MaxIdleConns至少 10 - 不要在 handler 里 new client，应在服务启动时初始化一次并复用：
var smsClient *sms.Client全局变量 or 依赖注入 - 务必用
defer c.Request.Body.Close()防止连接复用失败；若用c.ShouldBindJSON(&req)，它内部已处理，但手动读 body 时必须 close - panic 多来自未捕获 SDK 的
errors.Is(err, context.DeadlineExceeded)，应在调用后立即判断：if err != nil && !strings.Contains(err.Error(), "DeadlineExceeded")再记录 error 日志
验证码发送成功，但用户收不到，排查路径是什么
不是代码问题，而是腾讯云侧链路问题：短信可能被运营商拦截、签名/模板未白名单、号码被标记为营销号、或用户手机开启了骚扰拦截。这类问题不会返回错误码，SendSms 成功返回 SendSmsResponse.SmsSendDetailList[0].Fee 为 1，但用户无感知。
快速验证步骤：
- 先用腾讯云控制台「调试工具」填同一手机号 + 同一模板，看能否收到——排除代码逻辑
- 查
SendSmsResponse.SmsSendDetailList[0].Code == "Ok"且Message == "send success"，确认腾讯云已发出去 - 登录腾讯云短信控制台 → 「发送记录」页，输入手机号查具体条目，看
status是success还是blocked（被拦截） - 若 status 是
success但用户没收到，基本是运营商侧问题，需联系腾讯云客服提供smsid查投递日志
真正难搞的是模板变量渲染失败——比如传了 "123456" 给 {1}，但模板写成「您的验证码是{1}，5分钟有效」，而用户看到「您的验证码是，5分钟有效」，这种不会报错，但体验崩坏。每次上线前必须拿真实号码走一遍全链路。
