简介：阿里云短信接口demo.zip是一份面向PHP开发者的阿里云短信服务接入示例，聚焦验证码发送、通知提醒、营销触达等常见业务，帮助解决从应用侧调用短信API到消息成功下发的全流程集成难题。压缩包为zip格式，整体约3.35MB，内含可直接使用的PHP SDK代码及调用示例，重点覆盖AccessKey鉴权参数初始化、短信模板变量替换、签名审核要求、同步与异步调用差异，以及基于阿里云错误码的异常处理与限流规避方法。目前已有274人学习，适合具备一定PHP基础并希望快速接入阿里云短信服务的中级开发者参考。阅读这份Demo，能更直观地理解SDK库文件的引入路径、SendSms等核心接口请求参数的组装顺序，并掌握在真实项目中安全保管密钥、设计重试与监控报警策略的要点，可显著降低短信功能的上手门槛和联调成本。
1. 阿里云短信接口 demo.zip：先搞懂这套资源能解决什么问题
如果你接手过任何带「手机号验证码」或「通知短信」功能的系统，大概率被短信服务折腾过：官方文档翻半天找不到一个能跑的完整示例，AccessKey 权限配错导致生产环境突然发不出短信，模板变量格式不对被服务商驳回……这份阿里云短信接口 demo.zip 的价值在于，它把从「申请签名模板」到「代码发出一条真实短信」的全流程收敛成一个可运行的工程，而不是把文档散页堆给你。它既适合刚接触阿里云短信服务的后端开发者，也适合需要快速在内部项目里接入短信能力的人。我用它做过一次原型验证，从解压到收到第一条测试短信，前后不到四十分钟。
2. 接入短信接口前：先看清算力与调用链的关系
2.1 短信服务并不是「填个 Key 就能发」：你面对的是三层鉴权
不少第一次接触阿里云短信接口的人，以为拿到 AccessKey ID 和 Secret 就能直接调接口。实际拆开这个 demo 会发现，调用链路里藏着三层必须对齐的东西：第一层是账号级鉴权，也就是 AccessKey ID 与 Secret 本身；第二层是业务级授权，签名和模板必须在控制台创建并审核通过；第三层才是接口参数层面的签名算法——把请求参数按字典序排序、拼接、计算 HMAC-SHA1 或 HMAC-SHA256，再放到请求里。三层任何一个没对上，返回的都是类似isv.SMS_SIGNATURE_ILLEGAL或SignatureDoesNotMatch这样的错误。
demo 包里的代码把这层逻辑封装好了，但你需要理解它封装了什么。拿 Python 版本来举例，它通常不是直接裸调 HTTP 接口，而是通过阿里云官方的aliyuncs.com网关，加上产品级 SDK。这样做的好处是签名算法已经由 SDK 处理，你的代码只需要关心业务参数：手机号、签名名称、模板编码、模板变量。坏处是，如果你后来换成裸 HTTP 调用，签名算法这块很容易翻车，这点在后文避坑部分会重点说。
2.2 为什么建议直接用 SDK，而不是自己拼请求
我见过不少人在接入短信时坚持「不用 SDK，自己写 HTTP 请求」，理由是轻量。但以这个 demo 的代码为参照，SDK 帮你省掉的事情比想象中多：参数排序规则、RFC 3986 编码规则、时间戳格式（UTC 时间的 ISO8601 格式）、签名字符串的构造……这些细节任何一个出错，返回的错误码都是泛化的SignatureDoesNotMatch，排查起来非常消耗时间。
这个 demo 的代码示例大体是下面这个骨架，先看主流程再解释参数：
from aliyunsdkcore.client import AcsClient from aliyunsdkcore.request import CommonRequest client = AcsClient( access_key_id='你的AccessKey ID', access_secret='你的AccessKey Secret', region_id='cn-hangzhou' ) request = CommonRequest() request.set_accept_format('json') request.set_domain('dysmsapi.aliyuncs.com') request.set_method('POST') request.set_protocol_type('https') request.set_version('2017-05-25') request.set_action_name('SendSms') request.add_query_param('PhoneNumbers', '13800138000') request.add_query_param('SignName', '你的签名名称') request.add_query_param('TemplateCode', 'SMS_123456789') request.add_query_param('TemplateParam', '{"code":"123456"}') response = client.do_action_with_exception(request) print(response)逻辑说明：AcsClient负责帮你处理签名、鉴权和地域路由，CommonRequest则是通用的请求载体，它允许你在不单独引入短信专用 SDK 的情况下构造任意 API 请求。do_action_with_exception会抛出异常而不是静默失败，所以调试阶段你能直接看到服务端返回的具体错误文本。参数方面，PhoneNumbers支持一次传入多个号码用逗号分隔，SignName必须是控制台里审核通过的签名，TemplateCode是模板的编号，TemplateParam里的 JSON 键名必须和模板变量完全对应——变量名不一致会直接报isv.TEMPLATE_MISSING_PARAMETER。
2.3 地域与 Endpoint：默认杭州节点，但你得知道为什么
这个 demo 里region_id基本写成cn-hangzhou，这是一个容易让人误解的地方。短信服务的 API 网关入口只有固定的几个地域节点，cn-hangzhou是默认也是覆盖全国流量的入口，并不代表你的业务服务器必须部署在杭州。你业务 ECS 在青岛、张家口或境外，照样可以指向杭州的短信网关。唯一要注意的是，如果将来你的业务量到百万级日发送量，且对延迟极度敏感，可以改到离你最近的地域节点。不过对 demo 级别的项目来说，保持默认即可，这个参数不影响签名模板的归属。
3. 拆开 demo 包：文件结构与第一个能跑通的调用
3.1 demo 包里的典型文件分工
阿里云短信接口 demo.zip 这类资源，解压后通常不是一个大而全的工程，而是按语言拆分成独立目录。常见的是python、java、php、nodejs四套，加上一个README或配置说明.txt。每个语言目录内，至少包含三个东西：配置文件或常量区、单发短信的调用入口、以及批量发送或查询发送状态的补充脚本。
以 Python 目录为例，文件名可能长这样：
python/ ├── sms_demo.py ├── sms_batch_demo.py ├── query_send_detail.py └── config.pyconfig.py一般是所有脚本共用的配置集中地，里面写着 AccessKey、签名名、模板编码；sms_demo.py是单发入口；sms_batch_demo.py演示SendBatchSms的多号码不同变量发送；query_send_detail.py用来查一条短信的发送状态和回执。你上手时，第一步应该是改config.py，而不是去动业务脚本。
3.2 把 demo 里的单个发送脚本改成你的配置：逐步操作
不管你是 Windows 还是 macOS，先把 demo 包解压，然后用 Python 3.8 以上版本运行。在改代码之前，先去阿里云控制台完成两件事：创建签名和创建模板。签名需要提供应用名称或网站名，模板内容必须是完整的一句话，不能带变量外的特殊符号。比如您的验证码为${code}，5分钟内有效，模板审核一般十分钟内完成。
接下来打开config.py，填写下面几项：
ACCESS_KEY_ID = "LTAI5t**********" # 主账号或 RAM 子账号的 AccessKey ID ACCESS_KEY_SECRET = "你的AccessKey Secret" SIGN_NAME = "你的应用签名" # 控制台签名管理里显示的签名名称，不需要带【】 TEMPLATE_CODE = "SMS_123456789" # 控制台模板管理里的模板CODE REGION_ID = "cn-hangzhou" # 保持默认即可逻辑说明：SIGN_NAME不要在两边加签名符号【】，控制台显示的时候会自动加，代码里只写中文签名本体。TEMPLATE_CODE是一个以SMS_开头的字符串，注意复制的时候别带空格。REGION_ID保持cn-hangzhou，它代表的是短信 API 网关的地域，不是你的业务地域。
改完后直接运行单发脚本：
cd python python sms_demo.py如果前面配置没出错，且模板变量填得正确，你填的手机号会在几秒内收到一条短信。第一次跑通后，你会注意到 demo 里的TemplateParam是一个硬编码的 JSON 字符串，实际项目中这个字符串必须动态生成，后面会讲怎么处理。
3.3 批量发送与查询回执：demo 里被低估的两个脚本
很多人用完单发脚本就丢了 demo，但批量发送和查询回执两个脚本在真实场景里更救命。sms_batch_demo.py处理的是「不同用户收到不同验证码」的场景，它的TemplateParam不再是一个 JSON，而是一个 JSON 数组，每个元素对应一个手机号的变量内容。query_send_detail.py则补足了「用户说没收到，怎么自证」这个需求——通过SendDate和PhoneNumber反查发送状态，返回SUCCESS不代表用户收到，只是代表运营商已受理，DELIVERED才是真正到达。
4. 把 demo 改造成自己项目里的短信模块：与业务代码融合
4.1 新增一个短信发送的服务层：参数动态化与异常收敛
demo 是给人手动跑的脚本，不是给人直接复制进生产代码的。我一般会做一层封装，把短信发送从业务代码里剥出来。核心要处理两件事：第一，TemplateParam必须从外部传入字典再序列化成 JSON；第二，所有返回结果要统一转换成业务侧的状态，不要让isv.BUSINESS_LIMIT_CONTROL这种错误直接泄露到前端。下面是一个最小封装模板：
import json from aliyunsdkcore.client import AcsClient from aliyunsdkcore.request import CommonRequest class SmsService: def __init__(self, access_key_id, access_key_secret, sign_name, template_code): self.client = AcsClient(access_key_id, access_key_secret, region_id='cn-hangzhou') self.sign_name = sign_name self.template_code = template_code def send_verify_code(self, phone, code): params = {"code": code} request = CommonRequest() request.set_accept_format('json') request.set_domain('dysmsapi.aliyuncs.com') request.set_method('POST') request.set_protocol_type('https') request.set_version('2017-05-25') request.set_action_name('SendSms') request.add_query_param('PhoneNumbers', phone) request.add_query_param('SignName', self.sign_name) request.add_query_param('TemplateCode', self.template_code) request.add_query_param('TemplateParam', json.dumps(params)) try: response = self.client.do_action_with_exception(request) result = json.loads(response) return result.get('Code') == 'OK' except Exception as e: # 记日志，并返回友好错误 return False逻辑说明：send_verify_code是验证码场景的专用方法，params字典的键必须与模板变量名一致。do_action_with_exception在签名错误、权限不足、频率超限时会抛出异常，这里全部捕获并返回False，业务层只需要判断布尔值。参数说明：code建议使用随机六位数字，且不要在前端生成后直接传入，而是在后端生成、存储、再发送，否则验证码的可预测性会成为安全隐患。这个类在业务代码里使用时，直接service = SmsService(...)后反复调用即可，不需要每次请求都重新 new 一个 client，AcsClient是线程安全的，可以作为单例长期持有。
4.2 存储验证码与发送记录：别忘了幂等和时间窗
接入短信接口后最常见的一个疏忽是把验证码只存在内存里。进程一重启，用户提交的验证码全部失效。我一般会在send_verify_code调用成功后，把验证码写入 Redis，设置五分钟过期；同时把phone、template_code、request_id、发送结果写入一张短信发送记录表。这张表的价值在排查用户投诉时非常大——用户说没收到，你查记录表能看到服务端返回的Code和RequestId，再用query_send_detail.py的逻辑去查回执，定位问题就快了。校验阶段则从 Redis 取值并比对，比对成功后立即删除，防止重放攻击。
import redis r = redis.Redis(host='127.0.0.1', port=6379, db=0) # 发送成功后写入 r.setex(f"sms:code:{phone}", 300, code) # 用户提交时校验 cached = r.get(f"sms:code:{phone}") if cached and cached.decode() == user_input: r.delete(f"sms:code:{phone}") # 校验通过 else: # 校验失败这里setex的第一个参数300是过期秒数，按业务需求调整；cached返回的是 bytes 对象，必须.decode()再比较。这套做法的好处是代码量不大，却把验证码的生命周期管住了。
4.3 多套模板时的路由策略：从硬编码到配置驱动
demo 里只有一个模板，实际业务里一般至少有三个：验证码模板、通知模板、营销模板。营销模板的发送时间和频次受严格限制，验证码模板则没有时间窗口限制。封装时可以在SmsService里维护一个模板字典：
TEMPLATES = { "verify": ("SMS_123456", "您的验证码为${code}，5分钟内有效"), "notice": ("SMS_654321", "您的订单已发货，快递单号${express_no}"), }调用时通过template_key传入键名，内部再从字典取模板编码。这样以后增改模板，只需在配置文件或常量里调整，不需要改动发送逻辑。模板内容那列是用来给开发者自己读的，实际发送以控制台审核通过的为准。
5. 避坑与常见问题：阿里云短信接口的五个高频翻车点
5.1SignatureDoesNotMatch签名不匹配
现象：代码完全照着 demo 改的，运行后返回SignatureDoesNotMatch或Specified signature is not matched with our calculation。 原因：绝大多数情况是AccessKey Secret复制多了空格或隐藏字符，或者使用了主账号的 Key 而主账号开启了多因素认证。另外，如果你修改过request的domain或version，签名算法需要把它们纳入计算，SDK 对此很敏感。 解决：先检查 Secret 前后是否干净；然后在控制台新建一个只授权短信服务权限的 RAM 子账号，用子账号的 Key 重新测试。如果仍然报错，把do_action_with_exception换成do_action并打印原始 HTTP 响应体，那里面会带RequestId，去控制台对应的 OpenAPI 排查页面查询具体错误原因。
5.2isv.SMS_SIGNATURE_ILLEGAL签名不合法
现象：模板审核通过，签名也显示已生效，但代码一直报签名不合法。 原因：SignName参数填了带【】的完整签名，比如填了【某应用】，但接口只接受某应用这段本体。另一种可能是签名刚审核通过，系统还没完成全量同步，有十到二十分钟的延迟。 解决：把SignName值里的【】去掉，只保留中文或英文原名。等待二十分钟后重试，如果还报错，去控制台确认签名状态是否为「已生效」，而不是「待审核」。
5.3isv.TEMPLATE_MISSING_PARAMETER模板变量缺失
现象：模板里的变量是${code}，代码里TemplateParam传了{"verificationCode":"123456"}，结果报变量缺失。 原因：模板变量名是code，你的 JSON 键名却是verificationCode，两者不完全一致。阿里云短信服务不关心语义，只做严格的字符串匹配。 解决：把 JSON 的键改成和模板变量名一模一样，注意大小写。如果你在控制台改过模板内容但没重新审核，实际生效的模板仍是旧的，也会出现这种错位。
5.4isv.BUSINESS_LIMIT_CONTROL触发限流
现象：测试时发得开心，突然报业务限流，手机收不到短信。 原因：短信服务对同一个签名、同一个模板、同一个手机号有频控规则。默认情况下，同一个手机号一分钟内最多一条，一小时最多五条，一天最多十条。你连续调试时用同一个手机号，很容易撞上限流。 解决：调试期准备两到三个手机号轮换用；生产环境发送前做本地拦截，比如验证码模块在写入 Redis 前判断该手机号是否已有有效验证码，有就直接复用，不发第二条。真被限流了，只能等频控窗口过去，没有后悔药。
5.5 回执状态DELIVERED但用户说没收到
现象：查询发送记录显示DELIVERED，用户手机上没有短信。 原因：手机本身把短信拦截到垃圾箱，或者用户在境外漫游，运营商下发通道有异常。 解决：先让用户检查拦截短信和垃圾箱；再确认用户手机号是否在携号转网后未更新号段数据。这两招都无效时，拿RequestId和接收号码去工单系统提交给技术支持查运营商侧的下发记录。
6. 最后一步：用发送回执验证你的接入质量
跑通 demo 只是起点，能拿到并解读回执才叫真正的接入完成。短信接口返回Code: OK只代表请求被接受，不代表用户收到。QuerySendDetails接口会返回SendStatus字段，1表示已发送，2表示发送失败，3表示已到达。我的习惯是在测试阶段写一个自查脚本，每次发完短信后隔三秒自动查询一次回执状态并打印：
def query_status(phone, send_date): request = CommonRequest() request.set_domain('dysmsapi.aliyuncs.com') request.set_version('2017-05-25') request.set_action_name('QuerySendDetails') request.add_query_param('PhoneNumber', phone) request.add_query_param('SendDate', send_date) request.add_query_param('PageSize', '1') request.add_query_param('CurrentPage', '1') resp = client.do_action_with_exception(request) detail = json.loads(resp) return detail.get('SmsSendDetailDTOs', {}).get('SmsSendDetailDTO', [{}])[0].get('SendStatus')SendDate的格式必须是YYYYMMDD，不要带时分秒。返回的SendStatus=3才是已到达。从那以后，我每次接入短信服务，不管用的是谁的 demo，都会强制走一遍「单发成功 -> 动态参数 -> 批量发送 -> 回执查询」的完整链路，确认每一项都能闭环后才算交付。这篇把 demo 的拆解写到这里，坑我已经替你踩过一圈，剩下的就是你自己动手把配置换成真实信息、跑通第一条短信。希望帮到你。
本文还有配套的精品资源，点击获取
