准备阶段：3个核心配置项一个都不能少
很多人一开始就急着写代码，结果忙活半天发现短信发不出去，其实是前期准备没做好。去年帮一个电商客户集成短信登录功能时，我就踩过这个坑——当时跳过了模板变量校验，直接写代码，结果测试时返回“模板参数不匹配”，白白浪费了2小时。所以准备阶段这3件事，你一定要按顺序做好，一步都不能省。
先搞定账户与资质：签名和模板是重中之重
首先得有腾讯云账户，这个不用多说，直接去官网注册（https://cloud.tencent.com，nofollow），个人和企业都能注册，但企业账户的短信发送量限制会宽松很多。注册后记得完成实名认证，不然连测试短信都发不了。
然后是最关键的签名和模板申请。签名就是短信内容开头那个【】里的文字，比如【你的网站名】。这里有个坑：很多人随便填个签名就提交，结果审核被拒。根据腾讯云短信服务文档（https://cloud.tencent.com/document/product/382，nofollow），签名必须和你的网站、APP或企业名称一致，个人用户最好用“个人测试”+姓名的格式，比如【个人测试-张三】，这样审核通过率会高很多。我之前帮一个做工具类网站的朋友申请签名，一开始用【实用工具】被拒了，后来改成【实用工具网】（和他的域名一致），当天就通过了。
模板就是短信内容的固定格式，比如“您的验证码是{1}，{2}分钟内有效”。这里要注意，模板里的变量（就是{1}、{2}这种）数量和类型要记清楚，后面写代码时必须严格对应，多一个少一个都会报错。举个例子，如果你申请的模板是“您的验证码是{1}，{2}分钟内有效”，那发送时就必须传2个参数，第一个是验证码数字，第二个是有效期数字，顺序还不能错。
API密钥：安全保存比啥都重要
准备工作的最后一步是获取API密钥，这相当于你调用腾讯云接口的“钥匙”。登录腾讯云控制台，进入“访问管理”→“API密钥管理”，新建一对密钥（SecretId和SecretKey）。这里必须提醒你：千万不要把密钥直接写在前端代码里，也不要提交到GitHub上！去年有个客户就是不小心把密钥传到了公开仓库，结果被人盗用发送垃圾短信，一夜之间欠费2000多。正确的做法是把密钥存在服务器的环境变量里，或者用配置文件单独存放，权限设为只读。
为了让你更清楚准备阶段要做什么，我整理了一个检查清单，你可以对照着一步步来：
| 准备项 | 具体要求 | 常见错误 |
|---|---|---|
| 账户认证 | 完成实名认证，个人/企业均可 | 未认证导致发送权限被限制 |
| 签名申请 | 与网站/APP名称一致，含【】 | 签名与实际用途不符被拒 |
| 模板申请 | 变量数量和类型明确 | 模板含敏感词（如“中奖”）被拒 |
| API密钥 | 保存SecretId和SecretKey，禁止公开 | 密钥泄露导致账户被盗用 |
这个表格里的每一项都很关键，尤其是签名和模板， 你申请时多截几张图，把模板ID和变量数量记在笔记本上，后面写代码时会经常用到。
开发实战：3行核心代码打通短信发送全流程
准备工作做好后，就可以开始写代码了。很多人觉得PHP调用API很难，其实腾讯云已经提供了现成的SDK（软件开发工具包），我们不用自己处理复杂的加密和请求格式，直接调用SDK里的方法就行。我之前带过一个零基础的实习生，按照这个步骤，他用了40分钟就成功发送了第一条测试短信，你肯定也能行。
第一步：安装SDK，5分钟搞定环境配置
首先要在你的PHP项目里安装腾讯云短信SDK。如果你用Composer管理依赖（现在大部分PHP项目都会用），直接在终端运行这行命令：
composer require tencentcloud/tencentcloud-sdk-php如果没装Composer也没关系，去腾讯云SDK的GitHub仓库（https://github.com/TencentCloud/tencentcloud-sdk-php，nofollow）下载源码，解压后把src/TencentCloud文件夹复制到你的项目目录里，然后用require_once引入就行。这里要注意PHP版本，SDK要求PHP 5.6以上， 用PHP 7.2及以上版本，兼容性更好。
安装完成后，先写一段简单的代码测试SDK是否能正常加载。新建一个test_sdk.php文件，输入以下代码：
<?php require_once 'vendor/autoload.php'; // 如果用Composer引入
// require_once 'path/to/TencentCloud/Sms/V20210111/SmsClient.php'; // 如果手动引入
use TencentCloudSmsV20210111ModelsSendSmsRequest;
echo "SDK加载成功！";
?>
在浏览器里访问这个文件，如果显示“SDK加载成功！”，说明环境没问题；如果提示“Class not found”，检查一下文件路径是否正确，或者Composer有没有安装成功。
第二步：编写核心发送代码，3行关键代码搞定逻辑
环境没问题后，就可以写发送短信的核心代码了。其实关键代码只有3行：创建客户端、构造请求、发送请求。我来带你一步步写，每一步都解释清楚为什么要这么做。
首先创建一个send_sms.php文件，先引入SDK并定义必要的参数。这些参数你需要替换成自己的：
<?php require_once 'vendor/autoload.php';
use TencentCloudCommonCredential;
use TencentCloudCommonProfileClientProfile;
use TencentCloudCommonProfileHttpProfile;
use TencentCloudSmsV20210111SmsClient;
use TencentCloudSmsV20210111ModelsSendSmsRequest;
// 替换成你的SecretId和SecretKey
$secretId = "你的SecretId";
$secretKey = "你的SecretKey";
// 替换成你的短信应用ID（在腾讯云短信控制台的“应用管理”里看）
$appId = "1400000000";
// 替换成你的签名内容（不带【】）
$signName = "你的签名";
// 替换成你的模板ID
$templateId = "123456";
// 接收短信的手机号，多个号码用数组
$phoneNumbers = ["+8613800138000"]; // 注意要带+86
// 模板参数，和你申请的模板变量对应，比如模板是{1}和{2}，这里就传两个参数
$templateParamSet = ["123456", "5"]; // 第一个是验证码，第二个是有效期（分钟）
?>
接下来是核心的3行代码。第一行创建认证对象，把SecretId和SecretKey传进去，腾讯云会通过这个认证你的身份：
// 创建认证对象
$cred = new Credential($secretId, $secretKey);
第二行创建HTTP配置和客户端对象，指定接口的地域（短信接口用“ap-guangzhou”即可，不用改）：
// 创建客户端对象
$httpProfile = new HttpProfile();
$httpProfile->setEndpoint("sms.tencentcloudapi.com"); // 短信接口固定地址
$clientProfile = new ClientProfile();
$clientProfile->setHttpProfile($httpProfile);
$client = new SmsClient($cred, "ap-guangzhou", $clientProfile);
第三行构造发送请求并调用接口。这里要把前面定义的参数都传进去，然后用SendSms方法发送：
// 发送短信
$req = new SendSmsRequest();
$req->setSmsSdkAppId($appId);
$req->setSignName($signName);
$req->setTemplateId($templateId);
$req->setPhoneNumberSet($phoneNumbers);
$req->setTemplateParamSet($templateParamSet);
$resp = $client->SendSms($req); // 发送请求
print_r($resp); // 输出返回结果
?>
把这些代码放在一起，保存后在终端运行php send_sms.php，如果一切正常，会输出类似这样的结果：
object(TencentCloudSmsV20210111ModelsSendSmsResponse)#17 (2) {
["SendStatusSet"]=>
array(1) {
[0]=>
object(TencentCloudSmsV20210111ModelsSendStatus)#18 (5) {
["SerialNo"]=>
string(28) "2109281234567890123456789012"
["PhoneNumber"]=>
string(13) "+8613800138000"
["Fee"]=>
int(1)
["Code"]=>
string(3) "Ok"
["Message"]=>
string(2) "OK"
}
}
["RequestId"]=>
string(36) "a1b2c3d4-5678-90ef-ghij-klmnopqrstuv"
}
看到Code是“Ok”，就说明短信发送成功了！这时候你手机应该能收到短信，内容就是你申请的模板格式，比如“【你的签名】您的验证码是123456，5分钟内有效”。
第三步：错误处理与调试，90%的问题都能这样解决
就算你严格按步骤来，也可能遇到发送失败的情况。我帮客户调试时，遇到最多的问题就是返回“InvalidParameter.TemplateParamMismatch”（模板参数不匹配）。这时候不用慌，按这几个步骤排查，90%的问题都能解决：
首先看返回的错误码，腾讯云的错误码都有详细说明（https://cloud.tencent.com/document/product/382/52073，nofollow）。比如“InvalidParameter.TemplateParamMismatch”就是模板参数数量不对，你申请的模板有2个变量，结果代码里只传了1个，或者传了3个，这时候检查$templateParamSet数组的长度，和模板变量数量一致就行。
还有一个常见错误是“InvalidParameter.SignatureNotExist”（签名不存在），这通常是因为你传的$signName和审核通过的签名不一致，比如审核通过的是【我的网站】，你代码里写成了【我的站点】，或者多了个空格，仔细核对一下签名内容。
如果还是找不到问题，可以用腾讯云提供的“在线接口调试”工具（https://console.cloud.tencent.com/api/explorer?Product=sms&Version=2021-01-11&Action=SendSms，nofollow），在网页上填写参数发送测试短信，对比网页上的参数和你代码里的参数，就能发现哪里填错了。我之前有个客户就是因为手机号没加“+86”，用调试工具一试就找到了问题。
你在代码里加上错误捕获，这样生产环境中出问题时能快速定位。比如用try-catch包裹发送请求：
try {
$resp = $client->SendSms($req);
// 发送成功，处理返回结果
if ($resp->SendStatusSet[0]->Code == "Ok") {
echo "短信发送成功！";
} else {
echo "发送失败：" . $resp->SendStatusSet[0]->Message;
}
} catch (Exception $e) {
// 捕获异常，输出错误信息
echo "接口调用失败：" . $e->getMessage();
}
这样就算出问题，也能看到具体的错误原因，不用猜来猜去。
按这3步操作下来，你应该已经能成功发送短信了。记得把示例代码里的“你的XXX”替换成自己的实际信息，尤其是API密钥和模板ID，千万别直接用示例值。如果发送成功，手机收到短信的那一刻，你会发现原来集成腾讯云短信这么简单。如果你按这些步骤试了，遇到解决不了的问题，欢迎在评论区告诉我错误码，我帮你看看怎么回事！
一般来说，腾讯云短信的签名审核不会拖太久，差不多1-2个工作日就能有结果。不过要注意，工作日的上午9点到下午6点之间提交的话，处理会快一些，毕竟审核人员都在上班时间集中处理这些申请，要是周五下午快下班才提交，可能就得等下周一了。
不过有时候审核会失败，我之前帮一个朋友处理的时候就遇到过，他当时随便填了个“我的小店”当签名，结果被打回来了。后来才知道，个人用户用企业名称当签名肯定不行，还有没完成实名认证的话，审核根本不会通过——这就像你去银行办业务，没带身份证肯定办不了。 如果签名里有“中奖”“验证码”这种词，单独用也容易被拒，这些词其实更适合放在短信模板里，而不是签名里。想提高通过率的话，个人用户其实可以用“个人测试-姓名”这种格式，比如【个人测试-李四】，这样审核人员一看就知道是个人测试用的，不容易出错；企业用户就简单了，直接用营业执照上的公司名，或者和网站备案信息一致的名称，比如你的网站备案是“XX科技有限公司”，签名就用【XX科技】，基本都能过。
签名审核需要多长时间？为什么会审核失败？
腾讯云短信签名审核通常在1-2个工作日内完成（工作日9:00-18:00处理较快）。审核失败常见原因包括：签名与实际用途不符（如个人用户用企业名称作为签名）、未完成实名认证、签名含敏感词（如“中奖”“验证码”等需配合模板使用的词单独作为签名）。 个人用户使用“个人测试-姓名”格式（如【个人测试-张三】），企业用户使用与营业执照或网站备案一致的名称，可提高通过率。
模板参数如何正确设置？数量必须和模板一致吗？
模板参数必须与申请的短信模板变量数量、顺序完全一致。例如模板内容为“您的验证码是{1}，{2}分钟内有效”，则代码中需传入包含2个元素的数组（如[“123456”, “5”]），第一个元素对应{1}（验证码），第二个对应{2}（有效期）。少传、多传或顺序错误都会返回“模板参数不匹配”错误。 申请模板时记录变量数量和含义，编写代码时逐一对应。
发送短信返回错误码时，如何快速排查问题？
首先查看返回的错误码（如InvalidParameter.TemplateParamMismatch），通过腾讯云短信错误码文档（https://cloud.tencent.com/document/product/382/52073，nofollow）查询具体原因。常见排查方向：① 检查签名是否已审核通过且与代码中一致；② 确认模板ID和参数数量是否匹配；③ 手机号格式是否正确（需带+86前缀，如+8613800138000）；④ API密钥是否正确且未泄露。若仍无法解决，可使用腾讯云“在线接口调试”工具对比参数差异。
使用腾讯云短信会产生费用吗？有免费额度吗？
腾讯云短信对新用户提供一定免费额度（通常为100条国内短信），具体以官网最新活动为准。免费额度用尽后按条计费，国内短信价格约0.04-0.07元/条（量大可申请折扣），国际短信价格因地区而异。 在控制台“费用中心”设置余额预警，避免因欠费导致服务中断。个人用户测试时可先使用免费额度，正式上线前预估用量并充值。
集成腾讯云短信对PHP版本有要求吗？需要安装哪些扩展？
腾讯云短信PHP SDK要求PHP 5.6及以上版本，推荐使用PHP 7.2及以上（兼容性更好，性能更优）。需确保服务器已安装curl扩展（用于发送HTTP请求）和json扩展（解析接口返回数据）。使用Composer安装SDK时，会自动检查并提示依赖缺失；手动引入时，需确保PHP配置中开启了上述扩展。可通过phpinfo()函数查看当前PHP版本和已安装扩展。
