简介阿里云短信接口demo.zip是一份面向PHP开发者的短信服务集成示例包旨在帮助快速掌握阿里云短信API的调用流程。压缩包内提供PHP SDK及配套示例代码涵盖AccessKey鉴权配置、SendSms发送接口调用、短信模板与签名设置、同步/异步调用选择及异常处理等关键环节。短信模板支持变量动态替换例如验证码模板可定义为“您的验证码是${code}”签名则需在控制台预先审核这些细节在demo中均有体现。包体大小约3.35MB轻量易用目前已有274人浏览学习。通过该demo读者可以直观理解SDK初始化、参数组装与请求发送的完整链路并据此扩展业务逻辑减少对接官方文档的摸索时间。整体代码结构清晰注释与示例便于按步骤调试是一份实用性较强的入门参考资料。1. 阿里云短信接口 Demo拿到手别急着跑先看懂这几件事做系统开发的人迟早会碰到一个需求给用户发验证码、发通知、发营销短信。市面上短信服务很多但阿里云短信接口因为文档全、SDK 完善、接口稳定几乎是很多人接短信能力的第一站。你下载到的这份 demo 包解决的问题就是把「开发环境能收到短信」这条链路完整跑通从 AccessKey 配置、签名和模板申请到调用发送接口、解析返回结果整个过程不需要自己从头去啃官方文档里那些分散的章节。适合刚接触短信服务、想快速看明白调用方式的人也适合已经在别家平台接通过短信、想迁移到阿里云上的开发者。我这里把整个 demo 拆开讲清楚顺带把最容易卡住你的地方标出来。2. 接短信前先立住架子AccessKey、签名与模板三件套很多人拿到 demo 后的第一反应是去改代码里的手机号然后直接运行结果大概率是报错。因为短信接口和普通 HTTP 接口不一样它在发送前有严格的资质校验你是谁、你以什么身份发、你发的短信内容长什么样。这三件事分别对应 AccessKey、签名和模板。2.1 开通短信服务与账号角色隔离打开短信服务控制台之前先想清楚一件事用主账号 AccessKey 还是子账号 AccessKey。常见做法是创建一个 RAM 子用户只授予AliyunDysmsFullAccess权限。原因很朴素短信接口涉及资费消耗主账号 Key 一旦泄露别人可以拿你的账号给任意手机号发短信一笔一笔都是钱。创建子账号时建议把编程访问AccessKey ID/AccessKey Secret打开记住这两串值。很多人踩过同一个坑创建完子账号之后没保存 Secret页面一关就找不到了只能重建。demo 里通常会把 AccessKey 写在一个config文件或者环境变量里你拿到代码后第一步就是检查这份配置有没有被硬编码进源码如果有先拆出来。开通短信服务本身很简单控制台里找到短信服务点开通即可但要注意开通之后还分国内短信和国际/港澳台短信demo 通常默认走国内短信。如果你要发的是海外验证码接口域名和产品 Code 都不一样代码里那套不能直接照搬。2.2 签名和模板卡住大部分人的审核环节签名和模板是两样东西不是一回事。签名是短信开头【】里的内容比如【某公司】模板是短信正文的骨架里面有 ${code} 这样的占位符。审核通过之前就算代码完全正确也发不出短信返回的错误码一般是isv.SMS_SIGNATURE_ILLEGAL或者isv.SMS_TEMPLATE_ILLEGAL。审核环节最影响效率的是材料。个人开发者申请签名需要提供对应的应用名称或网站域名截图企业签名要提供营业执照。模板这边验证码类模板通常写成「您的验证码为${code}您正在使用登录功能请勿泄露给他人。」注意${code}变量必须用英文大括号包裹中文括号、全角符号都会导致审核不通过。实际测试的时候建议先申请一个测试签名、一个测试模板。测试签名可以用「阿里云短信测试」模板用「您的验证码是${code}如非本人操作请忽略。」审核速度通常很快等正式环境要上线之前再提交正式签名和模板。demo 里一般会有一个templateCode和signName的配置项你先填测试值跑通再换成正式值。2.3 demo 的目录结构与配置读取逻辑大多数阿里云短信接口 demo 包的结构都不复杂。解压后你通常会看到src目录、pom.xml或requirements.txt以及一个README。如果 demo 是用 Java 写的配置文件多半是application.properties或config.properties里面放 AccessKey、签名、模板编号如果演示是用 Python 写的配置往往直接放在send_sms.py的顶部常量区。拿到代码先不着急运行按这个顺序过一遍确认 SDK 版本和构建文件里的依赖坐标有没有过时看配置文件里有没有占位符需要替换确认代码里填写的 Region 和 Endpoint 是否匹配找到真正发起请求的SendSmsRequest对象看它绑定了哪些字段举个例子Java 版的 demo 核心依赖通常是com.aliyun dyplsapi20170525 // 有些版本是 dysmsapi20170525注意区分这里有一个经常让人翻车的细节短信发送用的是dysmsapi这个产品包不是dyplsapi号码隐私保护。两个包的类名结构非常相似但接口语义完全不同。如果 pom 里引错了包编译不会报错但运行时会抛出ApiDoesNotExist。所以第一步先核对产品 Code别盯着代码里是不是SendSms看要看包名。配置读取逻辑上我见过两种写法一种是从环境变量读一种是从 properties 文件读。环境变量读法适合部署到服务器上用properties 文件法适合本地调试。demo 包为了让你能立刻跑起来多半会用 properties 文件硬编码一个默认值。你拿到之后第一件事应该是把真实的 Secret 填进去或者改成读取环境变量避免密钥跟着项目一起提交到仓库。3. 核心代码拆解从配置到短信发出的完整链路搞清楚前置条件之后进入代码层面。这一章把 demo 里发送短信的完整链路拆开按「初始化客户端 → 构造请求 → 解析响应」三块看。每一步都有参数细节错一个都会导致发送失败。3.1 初始化客户端Region 与 Endpoint 的选型客户端初始化是整个发送链路的起点。以 Java 版为例常见写法如下你需要关注两个点产品类型和 Region。DefaultProfile profile DefaultProfile.getProfile( cn-hangzhou, // regionId默认 cn-hangzhou accessKeyId, // 你的 AccessKey ID accessKeySecret); // 你的 AccessKey Secret DefaultProfile.addEndpoint(cn-hangzhou, cn-hangzhou, Dysmsapi, dysmsapi.aliyuncs.com); IAcsClient client new DefaultAcsClient(profile);逻辑说明这里通过DefaultProfile把账号信息和地区信息绑在一起再通过addEndpoint显式声明短信服务的 Endpoint。DefaultAcsClient拿着这份 profile 去构造 HTTP 请求。为什么要手动 addEndpoint因为某些新地域的可用区不在 SDK 默认的 Endpoint 列表里不手动声明会报InvalidEndpoint。参数说明regionId可以填你 ECS 所在的地域也可以直接填cn-hangzhou短信服务是公共级别的 API不绑定某个具体资源地域选cn-hangzhou几乎不会出错。Dysmsapi就是产品 Code 的另一种写法注意大小写阿里云对外文档里统一写作Dysmsapi写错之后 SDK 找不到对应路由。如果 demo 用的是新版 SDK写法会换成com.aliyun.dysmsapi20170525.Client与之对应的是直接 new 一个Client参数里传入endpoint。两种写法在功能上等价但老 SDK 依赖版本坑更多建议你在 pom 里锁定依赖版本号不要用latest。真实环境里经常有人因为某个 ApiProduct 版本不一致导致兼容问题现象是本地跑通、服务器上报NoSuchMethodError。锁定版本之后两边保持一致问题自然消失。3.2 构造发送请求参数绑定与预处理发送短信的请求构造是 demo 的核心代码。下面是精简版的发送方法结构CommonRequest request new CommonRequest(); request.setSysMethod(MethodType.POST); request.setSysDomain(dysmsapi.aliyuncs.com); request.setSysVersion(2017-05-25); request.setSysAction(SendSms); // 以下为业务参数 request.putQueryParameter(RegionId, cn-hangzhou); request.putQueryParameter(PhoneNumbers, phoneNumber); request.putQueryParameter(SignName, signName); request.putQueryParameter(TemplateCode, templateCode); request.putQueryParameter(TemplateParam, {\code\:\123456\});逻辑说明CommonRequest不依赖具体产品实体类通过putQueryParameter直接塞参数适合快速调试和翻看 demo。PhoneNumbers就是要接收短信的手机号单次调用只能填一个号码要带国家码但不带号国内直接写 11 位手机号。SignName和TemplateCode从控制台复制过来填写注意大小写和空格已经审核通过的内容复制出来不会错手敲就很容易把中文括号里看不见的空格带进去。参数说明TemplateParam是一个 JSON 字符串里面定义的 key 要和模板中${}占位符名字完全一致。模板里写的是${code}这里就填{code:123456}。如果模板里有多个变量写成{code:123456,product:某应用}不能多、不能少、不能改名否则返回isv.TEMPLATE_PARAMS_ILLEGAL。值得单独提醒的坑phoneNumber如果写成全局变量循环发送时容易残留上一次的值。demo 代码里往往是单次调用复制出来改成多线程调用时要注意每种请求对象都应是独立的不要在循环外复用同一个 Request 实例。之前见过一个案例一个开发者把CommonRequest定义在 for 循环外面第二次循环时putQueryParameter覆盖了参数导致同一批数据给同一个人发了短信其他人全发到第一个号码上。这种问题排查起来很痛苦因为单次运行完全正常。3.3 返回结果判断SendSmsResponse 的解读发送之后立刻能拿到一句返回值但这句话的信息量比你想的大。代码通常会这么写CommonResponse response client.getCommonResponse(request); System.out.println(response.getData()); // 常见返回{Message:OK,RequestId:...,Code:OK,BizId:...}逻辑说明发送请求发出后返回内容是Code和Message两个核心字段。只有Code OK才表示请求被短信平台接收。注意是「接收」不是「已送达」。BizId是一个流水号后面查发送详情、回执状态时要拿它去换。很多第一次接的人看到OK就觉得短信一定到了实际可能有延迟也可能被运营商拦截后面第 6 章会讲怎么验证。参数说明RequestId用于向技术支持排查问题每次请求唯一。返回非 OK 的 Code先把 Message 贴到官方错误码文档里查常见的像isv.MOBILE_NUMBER_ILLEGAL表示号码非法isv.SMS_SIGNATURE_ILLEGAL表示签名未通过或不存在isv.SMS_TEMPLATE_ILLEGAL表示模板问题。逐个查一遍比自己瞎改配置快得多。一个比较隐蔽的情况如果接口返回OK但短信确实没收到多半不是接口问题了往下看第 5 章那里针对这类问题整理了排查路径。4. 参数怎么调手机号、模板变量与频率限制的边界跑通一次发送之后就到了调参数的阶段。参数改起来不难但边界搞不清楚会连续翻车。这一章围绕手机号格式、模板变量的编码边界、频率限制三个方向展开。4.1 模板变量 JSON 的坑占位符与编码模板变量TemplateParam一共三个容易出错的地方类型、编码、字面匹配。类型问题上官方文档写的是 JSON 字符串但实际接口解析对内容有严格要求必须是合法的 JSON并且 key 必须是字符串。简单验证码场景写成{code:123456}没问题但如果你要发送的内容里包含中文比如通知模板里有一句「您预约的门店因故暂停营业」这个 value 在组装时就会被 URL 编码。有些语言在 HTTP 请求层会自动转码有些不会。最常见的玄学问题出现在引号上TemplateParam最外层用双引号内层 value 也是双引号当你在 Java 里拼字符串时内部引号需要转义。比如代码如下String templateParam {\code\:\123456\};如果写成了{code:123456}外层单引号在 HTTP 参数里会被原样传递接口解析 JSON 时直接失败。还有一种情况是模板变量内容长度超限。验证码模板的理论边界是单个变量值不超过 30 个字符整体短信内容加上签名不超过 500 字或 70 字符按字符集和计费规则变动。实际调优时把变量控制在 20 个字以内是安全的做法避免运营商在网关层做内容截断。4.2 手机号校验不只 11 位这么简单PhoneNumbers参数的边界不仅仅是「11 位数字」。整套校验规则是这样的支持国内号码也支持加国家码的国际号码但国内号码写 11 位、不带86前缀如果带国家码格式是8613812345678这种不能有空格、短横线、括号。很多 demo 里只做正则^1[3-9]\d{9}$校验这只覆盖了移动、联通、电信的常用号段。一些虚拟运营商号段、物联网卡号段不在这个正则里但可以正常收短信。你要是把正则当硬校验写入业务会误伤一部分真实用户。常见做法是只做空值和长度校验格式合法性交给短信平台返回码来判断。还有一点容易被忽略同一个手机号在短时间内的发送频率。阿里云侧的限制是同一个号码验证码类短信默认一分钟内不能超过 1 条、一小时内不能超过 5 条、一天内不能超过 10 条具体数值以控制台配额为准。超过之后返回isv.BUSINESS_LIMIT_CONTROL。这个限制是保护用户不被骚扰也是保护你的账户余额。调频控参数时不要想着去接口里改参数逃避限流正确的做法是业务层做发送记录每次发送前查一下这个号码最近一分钟有没有发过。demo 代码里通常没有这个逻辑你需要自己补充一个简单的缓存计数。建议在接入阶段就加上否则上线第一天就会踩到提醒用户「验证码发送过于频繁」的文案。4.3 测试环境与线上环境的差异很多人在本地把 demo 跑通之后直接把同一个 AccessKey 和同样的签名模板发到生产环境。这里面至少有两条边界需要划清楚。第一条AccessKey 的权限边界。测试环境用一个只有短信权限的子账号生产环境用另一个子账号两个 Key 分开方便审计也方便出了问题单独吊销。混用同一个 Key排障时很难分清是测试调用量冲掉了配额还是线上流量真的异常。第二条模板是否区分正式和测试。测试模板通常内容比较随意比如「您的验证码是${code}」这种模板被线上用户收到观感极差。更关键的是测试模板可能在产品更新时被平台清理一旦被清理线上发送就会从正常变为报模板非法而且是在运行时报错不是发布时报错。所以生产环境一定要用单独申请的正式签名和正式模板不要想着省审核流程把测试模板一直用下去。第三个边界是调用入口的 Endpoint。测试环境为了省钱可以不开公网访问但短信接口本身就是公网 API不存在内网 Endpoint。有些团队会配一个代理出口注意代理不能对 HTTPS 做解密否则 SDK 的证书校验会失败返回RequestTimeout或握手失败。这个问题经常被误判为网络不通实际是代理层干了额外的事。5. 常见问题排查五个让人翻车的真实案例这里整理几个几乎每个接入者都会至少遇到一次的报错。每一条都按照「现象 → 原因 → 解决」来写你可以直接把对照当成手册用。5.1 报错InvalidAccessKeyId.NotFound找不到密钥现象代码运行后立即报InvalidAccessKeyId.NotFound或返回Message: Specified access key is not found。原因最常见的是 AccessKeyId 填错了复制的时候少了前几位或者把 LTAI 开头那串和 Secret 混在一起填到了同一个字段。另一个高频原因是两个环境混用调用了测试环境的 Key但请求打到生产环境 Endpoint两边账号体系不一致。解决先在控制台检查这个 AccessKey 是否存在、是否被禁用。然后核对代码里读取的配置来源明确 Key 对应的环境。最后用输出语句把实际传入的accessKeyId打出来对比控制台里那一串逐字符核对。不要只靠眼睛直接复制控制台的 Key 覆盖到配置里。5.2 返回成功但收不到短信成功不是终点现象接口返回CodeOKMessageOK但手机迟迟收不到短信。原因可能出现在三个位置。一手机号填写正确但该号码之前投诉过垃圾短信被运营商纳入了黑名单二短信内容命中了运营商敏感词网关层被静默拦截三手机本身把验证码短信放进了骚扰拦截分类。解决先看手机是否存在拦截然后拿一张新的 SIM 卡换号码测试。如果新号码能收到说明原号码被运营商级别屏蔽了这个情况短信平台也解不了。如果新号码也收不到登录短信服务控制台查看发送记录关注Status字段是否为DELIVERED如果长时间停留在SENT状态联系客服排查链路。5.3 签名和模板不匹配SIGNATURE_AND_TEMPLATE_NOT_MATCH现象提交发送后返回isv.SMS_SIGNATURE_AND_TEMPLATE_NOT_MATCH。原因签名和模板虽然各自都审核通过但不是同一个应用场景。比如签名申请时填的是「某商场」模板申请时填的场景是「某 App 登录验证」两者会判定不匹配。短信平台的规则是签名和模板必须在控制台内绑定同一场景或相关场景不能拿一个 App 的签名发另一个应用的模板内容。解决打开控制台看签名详情和模板详情确认签名所属应用场景。如果确实需要混用就把模板重新提交场景说明里写明包含该签名的业务或者把模板复制一份改名为对应的业务签名名称。改签名比改模板更复杂因为签名要重新审核所以在你创建模板时就要刻意保持签名和模板场景一致。5.4 触发流控BUSINESS_LIMIT_CONTROL现象某次发送返回isv.BUSINESS_LIMIT_CONTROL并且不是首次出现在业务高峰时频繁出现。原因同一号码高频发送或全局请求量超过了账户默认 QPS。后台的 QPS 默认值通常远低于你对账面上的预期测试时看不出等到正式使用时某个瞬间集中发验证码就会撞上。解决先看报错的Message是不是trigger business limit如果包含具体维度号码级 / 账户级对症处理。号码级限流按第 4.2 章说的发前检查缓存计数账户级 QPS 超限排查是否有循环重复调用多半是代码里 for 循环内没有停顿把请求优化为分批发送每批间隔至少 1 秒。如果你确认业务量真的需要更高配额在控制台提交工单申请提升 QPS。5.5 账户欠费导致发送失败最不想看到的那一种现象上午发送正常下午突然所有请求都返回isv.AMOUNT_NOT_ENOUGH或者返回Forbidden提示。原因短信是按量付费的服务账户余额扣完会立即停止服务。很多人充值后没有设置余额告警峰值时段把余额打穿接口就直接拒绝了。解决第一时间登录费用中心充值充值后通常几分钟内自动恢复。但更建议先在控制台设置余额告警阈值比如低于 100 元时通知到手机。另外一个习惯是在代码里把AMOUNT_NOT_ENOUGH这个错误码接上实时告警不要只依赖平台的通知机制。通过这个方式至少能让你在流量跑完之前介入。从那以后我每次接短信相关项目都会强制把余额告警和错误码告警一起做完不再裸奔上线。6. 进阶技巧批量发送、回执确认与限流自保基础发送跑通只是第一步。把短信接口接到真实业务里还需要解决三个问题批量发送怎么写、如何确认短信真正送达、以及如何防止自己的业务误伤自己。6.1 批量发送的两种姿势批量发送有两种路径。一种是循环单发每次构造一个SendSms请求前提是你处理好频率控制。另一种是官方提供的批量接口SendBatchSms一次调用可以发最多 1000 个号码但签名和模板只能各用一套。注意批量接口的模板变量不是单个 JSON 字符串而是 JSON 数组数组长度必须和号码数量一致。request.putQueryParameter(PhoneNumberJson, [\13900001111\,\13900002222\]); request.putQueryParameter(SignNameJson, [\某签名\,\某签名\]); request.putQueryParameter(TemplateParamJson, [{\code\:\123\},{\code\:\456\}]);逻辑说明PhoneNumberJson传的是号码数组 JSONSignNameJson传的是签名数组TemplateParamJson传的是模板变量数组。三者的顺序按索引一一对应每个号码配一组变量。很多人第一次写的时候会把PhoneNumberJson写成[13900001111,13900002222]这没问题重点在于数组里所有字符串都必须用双引号包裹不能用单引号否则接口无法解析。从工程角度看我还是建议大部分场景用循环单发而不是批量接口。批量接口一次调用虽然快但任何一个号码的参数异常会导致整个批次返回失败排查成本高。循环单发加一个计数器定位问题更直接。只有在营销活动、通知推送这类确实量大且内容完全一致的场景再去用批量接口。6.2 回执状态如何确认短信真的送达回到第 3.3 章的伏笔。CodeOK只代表短信服务接收了这条发送指令但这条短信最终是否到达用户手机要看回执状态。回执状态可以通过两种方式获取一种是在控制台逐条查看发送记录另一种是订阅回执消息到你的服务器。订阅回执是生产环境的标准做法。你在控制台配置一个 HTTP 回调地址短信平台在状态发生变化时比如送达、失败、被拦截向这个地址 POST 一条 JSON 数据。你需要做的只是提供一个稳定的公网接口验证请求头里的 Token然后解析report_status字段。这个字段可能是DELIVERED、UNDELIVERABLE等。拿到失败回执后决定是否做补偿。这里有一个很容易被忽视的关键点回调地址不要做成同步等待处理建议先把消息落到本地消息队列或者先存数据库再慢慢更新状态。因为回调并发量可能很大如果你的服务器在回调处理里做重试、查数据库、发通知等一系列操作响应变慢会让短信平台认为回调失败然后重复推送同一条回执最终造成状态被覆盖。6.3 最后的习惯接阿里云短信接口这件事说难不难说简单也不是填个 Key 就能跑。demo 给你的是一条最短路径但生产环境要走得稳必须自己加上回执确认、余额告警、频控缓存这三个东西。从那以后我每次接短信通道都会先按「测试签名 测试模板 子账号 Key」跑通全链路再换上正式签名和正式模板最后把告警和回执一起配齐。这套流程看起来多花半天时间但能省掉后面无数的半夜告警。希望帮到你。本文还有配套的精品资源点击获取 
长河君 · 2026/10/16 6:52:10 · 阅读 1.2k 阿里云短信接口Demo拆解：从AccessKey配置到错误排查全攻略
简介阿里云短信接口demo.zip是一份面向PHP开发者的短信服务集成示例包旨在帮助快速掌握阿里云短信API的调用流程。压缩包内提供PHP SDK及配套示例代码涵盖AccessKey鉴权配置、SendSms发送接口调用、短信模板与签名设置、同步/异步调用选择及异常处理等关键环节。短信模板支持变量动态替换例如验证码模板可定义为“您的验证码是${code}”签名则需在控制台预先审核这些细节在demo中均有体现。包体大小约3.35MB轻量易用目前已有274人浏览学习。通过该demo读者可以直观理解SDK初始化、参数组装与请求发送的完整链路并据此扩展业务逻辑减少对接官方文档的摸索时间。整体代码结构清晰注释与示例便于按步骤调试是一份实用性较强的入门参考资料。1. 阿里云短信接口 Demo拿到手别急着跑先看懂这几件事做系统开发的人迟早会碰到一个需求给用户发验证码、发通知、发营销短信。市面上短信服务很多但阿里云短信接口因为文档全、SDK 完善、接口稳定几乎是很多人接短信能力的第一站。你下载到的这份 demo 包解决的问题就是把「开发环境能收到短信」这条链路完整跑通从 AccessKey 配置、签名和模板申请到调用发送接口、解析返回结果整个过程不需要自己从头去啃官方文档里那些分散的章节。适合刚接触短信服务、想快速看明白调用方式的人也适合已经在别家平台接通过短信、想迁移到阿里云上的开发者。我这里把整个 demo 拆开讲清楚顺带把最容易卡住你的地方标出来。2. 接短信前先立住架子AccessKey、签名与模板三件套很多人拿到 demo 后的第一反应是去改代码里的手机号然后直接运行结果大概率是报错。因为短信接口和普通 HTTP 接口不一样它在发送前有严格的资质校验你是谁、你以什么身份发、你发的短信内容长什么样。这三件事分别对应 AccessKey、签名和模板。2.1 开通短信服务与账号角色隔离打开短信服务控制台之前先想清楚一件事用主账号 AccessKey 还是子账号 AccessKey。常见做法是创建一个 RAM 子用户只授予AliyunDysmsFullAccess权限。原因很朴素短信接口涉及资费消耗主账号 Key 一旦泄露别人可以拿你的账号给任意手机号发短信一笔一笔都是钱。创建子账号时建议把编程访问AccessKey ID/AccessKey Secret打开记住这两串值。很多人踩过同一个坑创建完子账号之后没保存 Secret页面一关就找不到了只能重建。demo 里通常会把 AccessKey 写在一个config文件或者环境变量里你拿到代码后第一步就是检查这份配置有没有被硬编码进源码如果有先拆出来。开通短信服务本身很简单控制台里找到短信服务点开通即可但要注意开通之后还分国内短信和国际/港澳台短信demo 通常默认走国内短信。如果你要发的是海外验证码接口域名和产品 Code 都不一样代码里那套不能直接照搬。2.2 签名和模板卡住大部分人的审核环节签名和模板是两样东西不是一回事。签名是短信开头【】里的内容比如【某公司】模板是短信正文的骨架里面有 ${code} 这样的占位符。审核通过之前就算代码完全正确也发不出短信返回的错误码一般是isv.SMS_SIGNATURE_ILLEGAL或者isv.SMS_TEMPLATE_ILLEGAL。审核环节最影响效率的是材料。个人开发者申请签名需要提供对应的应用名称或网站域名截图企业签名要提供营业执照。模板这边验证码类模板通常写成「您的验证码为${code}您正在使用登录功能请勿泄露给他人。」注意${code}变量必须用英文大括号包裹中文括号、全角符号都会导致审核不通过。实际测试的时候建议先申请一个测试签名、一个测试模板。测试签名可以用「阿里云短信测试」模板用「您的验证码是${code}如非本人操作请忽略。」审核速度通常很快等正式环境要上线之前再提交正式签名和模板。demo 里一般会有一个templateCode和signName的配置项你先填测试值跑通再换成正式值。2.3 demo 的目录结构与配置读取逻辑大多数阿里云短信接口 demo 包的结构都不复杂。解压后你通常会看到src目录、pom.xml或requirements.txt以及一个README。如果 demo 是用 Java 写的配置文件多半是application.properties或config.properties里面放 AccessKey、签名、模板编号如果演示是用 Python 写的配置往往直接放在send_sms.py的顶部常量区。拿到代码先不着急运行按这个顺序过一遍确认 SDK 版本和构建文件里的依赖坐标有没有过时看配置文件里有没有占位符需要替换确认代码里填写的 Region 和 Endpoint 是否匹配找到真正发起请求的SendSmsRequest对象看它绑定了哪些字段举个例子Java 版的 demo 核心依赖通常是com.aliyun dyplsapi20170525 // 有些版本是 dysmsapi20170525注意区分这里有一个经常让人翻车的细节短信发送用的是dysmsapi这个产品包不是dyplsapi号码隐私保护。两个包的类名结构非常相似但接口语义完全不同。如果 pom 里引错了包编译不会报错但运行时会抛出ApiDoesNotExist。所以第一步先核对产品 Code别盯着代码里是不是SendSms看要看包名。配置读取逻辑上我见过两种写法一种是从环境变量读一种是从 properties 文件读。环境变量读法适合部署到服务器上用properties 文件法适合本地调试。demo 包为了让你能立刻跑起来多半会用 properties 文件硬编码一个默认值。你拿到之后第一件事应该是把真实的 Secret 填进去或者改成读取环境变量避免密钥跟着项目一起提交到仓库。3. 核心代码拆解从配置到短信发出的完整链路搞清楚前置条件之后进入代码层面。这一章把 demo 里发送短信的完整链路拆开按「初始化客户端 → 构造请求 → 解析响应」三块看。每一步都有参数细节错一个都会导致发送失败。3.1 初始化客户端Region 与 Endpoint 的选型客户端初始化是整个发送链路的起点。以 Java 版为例常见写法如下你需要关注两个点产品类型和 Region。DefaultProfile profile DefaultProfile.getProfile( cn-hangzhou, // regionId默认 cn-hangzhou accessKeyId, // 你的 AccessKey ID accessKeySecret); // 你的 AccessKey Secret DefaultProfile.addEndpoint(cn-hangzhou, cn-hangzhou, Dysmsapi, dysmsapi.aliyuncs.com); IAcsClient client new DefaultAcsClient(profile);逻辑说明这里通过DefaultProfile把账号信息和地区信息绑在一起再通过addEndpoint显式声明短信服务的 Endpoint。DefaultAcsClient拿着这份 profile 去构造 HTTP 请求。为什么要手动 addEndpoint因为某些新地域的可用区不在 SDK 默认的 Endpoint 列表里不手动声明会报InvalidEndpoint。参数说明regionId可以填你 ECS 所在的地域也可以直接填cn-hangzhou短信服务是公共级别的 API不绑定某个具体资源地域选cn-hangzhou几乎不会出错。Dysmsapi就是产品 Code 的另一种写法注意大小写阿里云对外文档里统一写作Dysmsapi写错之后 SDK 找不到对应路由。如果 demo 用的是新版 SDK写法会换成com.aliyun.dysmsapi20170525.Client与之对应的是直接 new 一个Client参数里传入endpoint。两种写法在功能上等价但老 SDK 依赖版本坑更多建议你在 pom 里锁定依赖版本号不要用latest。真实环境里经常有人因为某个 ApiProduct 版本不一致导致兼容问题现象是本地跑通、服务器上报NoSuchMethodError。锁定版本之后两边保持一致问题自然消失。3.2 构造发送请求参数绑定与预处理发送短信的请求构造是 demo 的核心代码。下面是精简版的发送方法结构CommonRequest request new CommonRequest(); request.setSysMethod(MethodType.POST); request.setSysDomain(dysmsapi.aliyuncs.com); request.setSysVersion(2017-05-25); request.setSysAction(SendSms); // 以下为业务参数 request.putQueryParameter(RegionId, cn-hangzhou); request.putQueryParameter(PhoneNumbers, phoneNumber); request.putQueryParameter(SignName, signName); request.putQueryParameter(TemplateCode, templateCode); request.putQueryParameter(TemplateParam, {\code\:\123456\});逻辑说明CommonRequest不依赖具体产品实体类通过putQueryParameter直接塞参数适合快速调试和翻看 demo。PhoneNumbers就是要接收短信的手机号单次调用只能填一个号码要带国家码但不带号国内直接写 11 位手机号。SignName和TemplateCode从控制台复制过来填写注意大小写和空格已经审核通过的内容复制出来不会错手敲就很容易把中文括号里看不见的空格带进去。参数说明TemplateParam是一个 JSON 字符串里面定义的 key 要和模板中${}占位符名字完全一致。模板里写的是${code}这里就填{code:123456}。如果模板里有多个变量写成{code:123456,product:某应用}不能多、不能少、不能改名否则返回isv.TEMPLATE_PARAMS_ILLEGAL。值得单独提醒的坑phoneNumber如果写成全局变量循环发送时容易残留上一次的值。demo 代码里往往是单次调用复制出来改成多线程调用时要注意每种请求对象都应是独立的不要在循环外复用同一个 Request 实例。之前见过一个案例一个开发者把CommonRequest定义在 for 循环外面第二次循环时putQueryParameter覆盖了参数导致同一批数据给同一个人发了短信其他人全发到第一个号码上。这种问题排查起来很痛苦因为单次运行完全正常。3.3 返回结果判断SendSmsResponse 的解读发送之后立刻能拿到一句返回值但这句话的信息量比你想的大。代码通常会这么写CommonResponse response client.getCommonResponse(request); System.out.println(response.getData()); // 常见返回{Message:OK,RequestId:...,Code:OK,BizId:...}逻辑说明发送请求发出后返回内容是Code和Message两个核心字段。只有Code OK才表示请求被短信平台接收。注意是「接收」不是「已送达」。BizId是一个流水号后面查发送详情、回执状态时要拿它去换。很多第一次接的人看到OK就觉得短信一定到了实际可能有延迟也可能被运营商拦截后面第 6 章会讲怎么验证。参数说明RequestId用于向技术支持排查问题每次请求唯一。返回非 OK 的 Code先把 Message 贴到官方错误码文档里查常见的像isv.MOBILE_NUMBER_ILLEGAL表示号码非法isv.SMS_SIGNATURE_ILLEGAL表示签名未通过或不存在isv.SMS_TEMPLATE_ILLEGAL表示模板问题。逐个查一遍比自己瞎改配置快得多。一个比较隐蔽的情况如果接口返回OK但短信确实没收到多半不是接口问题了往下看第 5 章那里针对这类问题整理了排查路径。4. 参数怎么调手机号、模板变量与频率限制的边界跑通一次发送之后就到了调参数的阶段。参数改起来不难但边界搞不清楚会连续翻车。这一章围绕手机号格式、模板变量的编码边界、频率限制三个方向展开。4.1 模板变量 JSON 的坑占位符与编码模板变量TemplateParam一共三个容易出错的地方类型、编码、字面匹配。类型问题上官方文档写的是 JSON 字符串但实际接口解析对内容有严格要求必须是合法的 JSON并且 key 必须是字符串。简单验证码场景写成{code:123456}没问题但如果你要发送的内容里包含中文比如通知模板里有一句「您预约的门店因故暂停营业」这个 value 在组装时就会被 URL 编码。有些语言在 HTTP 请求层会自动转码有些不会。最常见的玄学问题出现在引号上TemplateParam最外层用双引号内层 value 也是双引号当你在 Java 里拼字符串时内部引号需要转义。比如代码如下String templateParam {\code\:\123456\};如果写成了{code:123456}外层单引号在 HTTP 参数里会被原样传递接口解析 JSON 时直接失败。还有一种情况是模板变量内容长度超限。验证码模板的理论边界是单个变量值不超过 30 个字符整体短信内容加上签名不超过 500 字或 70 字符按字符集和计费规则变动。实际调优时把变量控制在 20 个字以内是安全的做法避免运营商在网关层做内容截断。4.2 手机号校验不只 11 位这么简单PhoneNumbers参数的边界不仅仅是「11 位数字」。整套校验规则是这样的支持国内号码也支持加国家码的国际号码但国内号码写 11 位、不带86前缀如果带国家码格式是8613812345678这种不能有空格、短横线、括号。很多 demo 里只做正则^1[3-9]\d{9}$校验这只覆盖了移动、联通、电信的常用号段。一些虚拟运营商号段、物联网卡号段不在这个正则里但可以正常收短信。你要是把正则当硬校验写入业务会误伤一部分真实用户。常见做法是只做空值和长度校验格式合法性交给短信平台返回码来判断。还有一点容易被忽略同一个手机号在短时间内的发送频率。阿里云侧的限制是同一个号码验证码类短信默认一分钟内不能超过 1 条、一小时内不能超过 5 条、一天内不能超过 10 条具体数值以控制台配额为准。超过之后返回isv.BUSINESS_LIMIT_CONTROL。这个限制是保护用户不被骚扰也是保护你的账户余额。调频控参数时不要想着去接口里改参数逃避限流正确的做法是业务层做发送记录每次发送前查一下这个号码最近一分钟有没有发过。demo 代码里通常没有这个逻辑你需要自己补充一个简单的缓存计数。建议在接入阶段就加上否则上线第一天就会踩到提醒用户「验证码发送过于频繁」的文案。4.3 测试环境与线上环境的差异很多人在本地把 demo 跑通之后直接把同一个 AccessKey 和同样的签名模板发到生产环境。这里面至少有两条边界需要划清楚。第一条AccessKey 的权限边界。测试环境用一个只有短信权限的子账号生产环境用另一个子账号两个 Key 分开方便审计也方便出了问题单独吊销。混用同一个 Key排障时很难分清是测试调用量冲掉了配额还是线上流量真的异常。第二条模板是否区分正式和测试。测试模板通常内容比较随意比如「您的验证码是${code}」这种模板被线上用户收到观感极差。更关键的是测试模板可能在产品更新时被平台清理一旦被清理线上发送就会从正常变为报模板非法而且是在运行时报错不是发布时报错。所以生产环境一定要用单独申请的正式签名和正式模板不要想着省审核流程把测试模板一直用下去。第三个边界是调用入口的 Endpoint。测试环境为了省钱可以不开公网访问但短信接口本身就是公网 API不存在内网 Endpoint。有些团队会配一个代理出口注意代理不能对 HTTPS 做解密否则 SDK 的证书校验会失败返回RequestTimeout或握手失败。这个问题经常被误判为网络不通实际是代理层干了额外的事。5. 常见问题排查五个让人翻车的真实案例这里整理几个几乎每个接入者都会至少遇到一次的报错。每一条都按照「现象 → 原因 → 解决」来写你可以直接把对照当成手册用。5.1 报错InvalidAccessKeyId.NotFound找不到密钥现象代码运行后立即报InvalidAccessKeyId.NotFound或返回Message: Specified access key is not found。原因最常见的是 AccessKeyId 填错了复制的时候少了前几位或者把 LTAI 开头那串和 Secret 混在一起填到了同一个字段。另一个高频原因是两个环境混用调用了测试环境的 Key但请求打到生产环境 Endpoint两边账号体系不一致。解决先在控制台检查这个 AccessKey 是否存在、是否被禁用。然后核对代码里读取的配置来源明确 Key 对应的环境。最后用输出语句把实际传入的accessKeyId打出来对比控制台里那一串逐字符核对。不要只靠眼睛直接复制控制台的 Key 覆盖到配置里。5.2 返回成功但收不到短信成功不是终点现象接口返回CodeOKMessageOK但手机迟迟收不到短信。原因可能出现在三个位置。一手机号填写正确但该号码之前投诉过垃圾短信被运营商纳入了黑名单二短信内容命中了运营商敏感词网关层被静默拦截三手机本身把验证码短信放进了骚扰拦截分类。解决先看手机是否存在拦截然后拿一张新的 SIM 卡换号码测试。如果新号码能收到说明原号码被运营商级别屏蔽了这个情况短信平台也解不了。如果新号码也收不到登录短信服务控制台查看发送记录关注Status字段是否为DELIVERED如果长时间停留在SENT状态联系客服排查链路。5.3 签名和模板不匹配SIGNATURE_AND_TEMPLATE_NOT_MATCH现象提交发送后返回isv.SMS_SIGNATURE_AND_TEMPLATE_NOT_MATCH。原因签名和模板虽然各自都审核通过但不是同一个应用场景。比如签名申请时填的是「某商场」模板申请时填的场景是「某 App 登录验证」两者会判定不匹配。短信平台的规则是签名和模板必须在控制台内绑定同一场景或相关场景不能拿一个 App 的签名发另一个应用的模板内容。解决打开控制台看签名详情和模板详情确认签名所属应用场景。如果确实需要混用就把模板重新提交场景说明里写明包含该签名的业务或者把模板复制一份改名为对应的业务签名名称。改签名比改模板更复杂因为签名要重新审核所以在你创建模板时就要刻意保持签名和模板场景一致。5.4 触发流控BUSINESS_LIMIT_CONTROL现象某次发送返回isv.BUSINESS_LIMIT_CONTROL并且不是首次出现在业务高峰时频繁出现。原因同一号码高频发送或全局请求量超过了账户默认 QPS。后台的 QPS 默认值通常远低于你对账面上的预期测试时看不出等到正式使用时某个瞬间集中发验证码就会撞上。解决先看报错的Message是不是trigger business limit如果包含具体维度号码级 / 账户级对症处理。号码级限流按第 4.2 章说的发前检查缓存计数账户级 QPS 超限排查是否有循环重复调用多半是代码里 for 循环内没有停顿把请求优化为分批发送每批间隔至少 1 秒。如果你确认业务量真的需要更高配额在控制台提交工单申请提升 QPS。5.5 账户欠费导致发送失败最不想看到的那一种现象上午发送正常下午突然所有请求都返回isv.AMOUNT_NOT_ENOUGH或者返回Forbidden提示。原因短信是按量付费的服务账户余额扣完会立即停止服务。很多人充值后没有设置余额告警峰值时段把余额打穿接口就直接拒绝了。解决第一时间登录费用中心充值充值后通常几分钟内自动恢复。但更建议先在控制台设置余额告警阈值比如低于 100 元时通知到手机。另外一个习惯是在代码里把AMOUNT_NOT_ENOUGH这个错误码接上实时告警不要只依赖平台的通知机制。通过这个方式至少能让你在流量跑完之前介入。从那以后我每次接短信相关项目都会强制把余额告警和错误码告警一起做完不再裸奔上线。6. 进阶技巧批量发送、回执确认与限流自保基础发送跑通只是第一步。把短信接口接到真实业务里还需要解决三个问题批量发送怎么写、如何确认短信真正送达、以及如何防止自己的业务误伤自己。6.1 批量发送的两种姿势批量发送有两种路径。一种是循环单发每次构造一个SendSms请求前提是你处理好频率控制。另一种是官方提供的批量接口SendBatchSms一次调用可以发最多 1000 个号码但签名和模板只能各用一套。注意批量接口的模板变量不是单个 JSON 字符串而是 JSON 数组数组长度必须和号码数量一致。request.putQueryParameter(PhoneNumberJson, [\13900001111\,\13900002222\]); request.putQueryParameter(SignNameJson, [\某签名\,\某签名\]); request.putQueryParameter(TemplateParamJson, [{\code\:\123\},{\code\:\456\}]);逻辑说明PhoneNumberJson传的是号码数组 JSONSignNameJson传的是签名数组TemplateParamJson传的是模板变量数组。三者的顺序按索引一一对应每个号码配一组变量。很多人第一次写的时候会把PhoneNumberJson写成[13900001111,13900002222]这没问题重点在于数组里所有字符串都必须用双引号包裹不能用单引号否则接口无法解析。从工程角度看我还是建议大部分场景用循环单发而不是批量接口。批量接口一次调用虽然快但任何一个号码的参数异常会导致整个批次返回失败排查成本高。循环单发加一个计数器定位问题更直接。只有在营销活动、通知推送这类确实量大且内容完全一致的场景再去用批量接口。6.2 回执状态如何确认短信真的送达回到第 3.3 章的伏笔。CodeOK只代表短信服务接收了这条发送指令但这条短信最终是否到达用户手机要看回执状态。回执状态可以通过两种方式获取一种是在控制台逐条查看发送记录另一种是订阅回执消息到你的服务器。订阅回执是生产环境的标准做法。你在控制台配置一个 HTTP 回调地址短信平台在状态发生变化时比如送达、失败、被拦截向这个地址 POST 一条 JSON 数据。你需要做的只是提供一个稳定的公网接口验证请求头里的 Token然后解析report_status字段。这个字段可能是DELIVERED、UNDELIVERABLE等。拿到失败回执后决定是否做补偿。这里有一个很容易被忽视的关键点回调地址不要做成同步等待处理建议先把消息落到本地消息队列或者先存数据库再慢慢更新状态。因为回调并发量可能很大如果你的服务器在回调处理里做重试、查数据库、发通知等一系列操作响应变慢会让短信平台认为回调失败然后重复推送同一条回执最终造成状态被覆盖。6.3 最后的习惯接阿里云短信接口这件事说难不难说简单也不是填个 Key 就能跑。demo 给你的是一条最短路径但生产环境要走得稳必须自己加上回执确认、余额告警、频控缓存这三个东西。从那以后我每次接短信通道都会先按「测试签名 测试模板 子账号 Key」跑通全链路再换上正式签名和正式模板最后把告警和回执一起配齐。这套流程看起来多花半天时间但能省掉后面无数的半夜告警。希望帮到你。本文还有配套的精品资源点击获取