用Python与Twilio搭建短信通知系统：从监控告警到验证码

半夜手机突然震动，屏幕上跳出“服务器CPU使用率超过90%，请立即处理”的短信。这个场景对于任何一个运维或者独立开发者来说都不陌生。项目不大，但价值极高：用Python调用Twilio的API，几十行代码就能搭起一套可靠、可扩展的短信通知系统，让监控告警、业务提醒、验证码都能第一时间触达用户。

这套系统的应用场景远比想象中广：除了服务端异常告警，还可以做定时任务执行后的结果通知、扫码登录的验证码、商品库存变化的提醒、甚至老婆大人定的“下班顺手买牛奶”任务提醒。而且Twilio的API设计得很干净，文档也全，新手在半小时内就能跑通第一行短信代码。老手则可以基于它做高可用、多租户、带状态回执的完整通知平台。

这篇内容就围绕这个项目展开：从为什么选Twilio，到环境怎么配、代码怎么写，再到生产环境里会遇到哪些坑，我踩过的都会告诉你。适合刚学Python想做个能跑的项目的人，也适合已经在做运维平台、需要接入短信能力的开发者。

1. 项目背景与方案选型

1.1 为什么短信通知比邮件、App推送更“稳”

先说说为什么需要一个短信通知系统。很多人第一反应是“发邮件不就行了吗”。邮件确实免费，但触达率不稳定——用户的邮箱可能不常看，或者通知邮件直接被扔进垃圾箱。App推送的问题更大，用户没安装你的App就收不到，就算装了，iOS的push权限被关掉你也毫无办法。短信不一样，只要手机有信号，就会收到，而且用户对短信的容忍度天然比垃圾邮件高一些，因为短信通知往往和验证码、支付强相关，用户会认真看。

从技术角度讲，短信发送的核心链路是：你的服务器把消息内容，通过云通信平台的API提交给运营商，再由运营商下发到用户手机。你要实现的系统，本质上就是围绕这个链路做一层封装：发送请求、处理错误、管理状态、对接业务。

这里不讨论自建短信网关，完全没必要。自己对接运营商不但要申请实名制、资质、落地号码，还要处理各种诡异的协议差异，一个人干这种事纯属给自己找不痛快。云通信平台把最脏的活都干了，你只关心“把内容发出去，然后知道它到底有没有送达”。

1.2 Twilio和国内短信服务商的对比

国内常见的云厂商短信服务（阿里云、腾讯云）也很成熟，但注册流程相对复杂：需要实名认证、申请签名、配置模板，而且审核周期不短。Twilio最大的优势是API上手极快，注册就能拿到一个真实号码，代码一跑就能发短信，非常适合个人开发者做项目原型。

Twilio是国际老牌云通信公司，在开发者圈子里口碑很好，它的短信API使用REST风格，SDK覆盖Python、Node.js、Java等主流语言，文档里有大量可运行的示例。对做海外业务的人来说，Twilio几乎是默认选择，因为覆盖国家多，而且不需要自己对接各国运营商。

当然，Twilio也有缺点：一是价格比国内厂商贵，尤其发往中国大陆的短信，价格明显偏高；二是按号码月租收费，你买下的号码哪怕一个月一条短信都不发也要交钱；三是国内监管环境下，Twilio发送到国内手机号的短信偶尔会被运营商拦截或延迟，所以如果你主要是给国内用户发短信，建议把Twilio当研究项目，生产环境还是用国内服务商更合适。

1.3 这套系统的组件拆解

一套完整的Twilio短信通知系统可以拆成这几块：

• 发送端：你的Python应用。负责构造消息内容，调用Twilio REST API。
• Twilio平台：负责把消息路由到运营商网络，并提供状态回调Webhook。
• 接收端：目标手机号。这一步看似简单，但要注意地区码、号段验证、运营商拦截等问题。
• 状态回调：Twilio会异步通知你短信最终是已送达、失败还是被拒收，你可以接收这些状态做后续处理。

另外还有账号体系、费率处理、日志记录这些配套设施，但核心链路就这四条。理解了这个模型，后面的代码实现就有了地图。

2. 环境准备与账号配置

2.1 Python环境怎么弄最省心

这个项目对Python版本要求不苛刻，3.8以上都行。如果你电脑上还没装Python，我建议直接去python.org下载安装包，Windows安装时一定要勾选“Add Python to PATH”选项，不然命令行敲python会报“不是内部或外部命令”。

macOS上可以用Homebrew安装：brew install python@3.11。Linux（比如Ubuntu）一般是自带了Python，但版本可能偏老，可以用sudo apt install python3-venv先把虚拟环境工具补上。

我个人强烈建议在每个项目里都用虚拟环境，别直接往全局Python装包，不然过几个月你大概率会被各种包版本冲突逼疯。创建方式是：

mkdir sms-notification-system cd sms-notification-system python -m venv venv source venv/bin/activate # Windows下是 venv\Scripts\activate

激活后用which python检查一下，确认现在用的是虚拟环境里的解释器。编辑器用VS Code的话，右下角选择解释器时也指向venv里那个python即可。

2.2 安装Twilio Python SDK

Twilio官方的Python SDK包名叫twilio，直接用pip安装：

pip install twilio

这里有个小坑：如果你的环境里同时有老版Twilio和其他通信包的依赖冲突，建议先升级pip再装。另外，官方SDK会依赖requests和httpx这些基础库，装完后可以用下面的命令验证：

python -c "import twilio; print(twilio.__version__)"

能输出版本号就说明装好了。版本尽量保持较新，老版本的API调用方式有变化，比如旧版创建Client时传的account_sid和auth_token不再支持直接传字符串，要改用环境变量加载，我们等下会细说。

2.3 注册Twilio账号并拿到密钥

访问Twilio官网，点免费注册，邮箱验证后，Twilio会要求你填一个验证手机号（这个号码是用来验证你本人身份的，之后会作为“已验证收件人”白名单之一）。注册过程中最关键的一步是进入Console后，你会看到两串字符：

• Account SID：一串以AC开头的32位字符串，相当于你的账户ID。
• Auth Token：一串以SK开头的字符串，相当于你的账户密码。

这两样东西千万不能写在代码里提交到Git仓库。我见过太多人把密钥硬编码到脚本里然后不小心上传GitHub，没过多久账户就会被别人刷爆短信费。正确的做法是用环境变量，或者用python-dotenv加载本地.env文件。.env 文件本身要加进 .gitignore。

在项目里建一个.env文件：

TWILIO_ACCOUNT_SID=你的AC... TWILIO_AUTH_TOKEN=你的SK... TWILIO_PHONE_NUMBER=+1234567890

然后安装python-dotenv：

pip install python-dotenv

之后在代码开头用load_dotenv()即可把环境变量读进来。

2.4 购买一个能发短信的电话号码

登录Twilio Console，在Phone Numbers页面点“Buy a number”。搜索时建议选具备SMS能力的号码，然后根据你接收方的国家分别号找号码。比如你的业务主要是美国用户，就找美国的+1号段；如果给全球用户发，建议买一个国际号码。

号码是月租制的，大约每个月1美元左右。Twilio会给你免费试用额度（以美元计），首次注册大概有几美元，够你测试几十条短信。但在试用期内，你能发送的号码是受限的：除了自己注册时验证的号码外，其他号码必须先在用户群里添加到已验证号码清单里，否则会报21408错误。正式上线前，建议把账户升级为付费账号，解除这个限制。

购买号码后，Twilio会允许你设置一个“Messaging Service”，它是一个逻辑容器，可以配置发送策略、回调URL、消息生命周期等。为了简单，我这个项目先用单个号码直接发，先不要Messaging Service，等业务规模起来再迁移。

3. 核心代码实现：从一行短信到封装成模块

3.1 先跑通第一行短信

在虚拟环境里新建一个send_sms.py，写入：

from twilio.rest import Client account_sid = "你的AC..." auth_token = "你的SK..." client = Client(account_sid, auth_token) message = client.messages.create( to="+8613800138000", from_="+14150000000", body="Hello from Twilio!" ) print(message.sid)

然后把to换成你的真实手机号，from_换成你在Twilio Console里买到的那个号码。运行：

python send_sms.py

如果一切正常，控制台会打印一个以SM开头的message SID，这意味着Twilio已经接受了这条消息，几秒后你的手机上就会收到短信。

这一步为什么先不封装？因为先跑通最小闭环很重要，后面所有问题你都好定位是环境问题还是代码问题。我第一次做的时候就是直接复制官方示例，把密钥放进去先跑成功，建立了信心，再回头重构。

3.2 用环境变量管理密钥，消除硬编码

创建config.py或直接在入口文件顶部加载env。最省事的方式是创建一个settings.py：

import os from dotenv import load_dotenv load_dotenv() TWILIO_ACCOUNT_SID = os.getenv("TWILIO_ACCOUNT_SID") TWILIO_AUTH_TOKEN = os.getenv("TWILIO_AUTH_TOKEN") TWILIO_PHONE_NUMBER = os.getenv("TWILIO_PHONE_NUMBER")

这样不但安全，而且换账号、换号码只需要改.env，不用改代码。最重要的一个好处：如果你的代码要部署到服务器或云函数平台，环境变量可以直接在平台控制台配置，而不用把密钥写进代码打包，这是最小安全隐患。

3.3 中文内容处理与160字符分段

Twilio API支持UTF-8，所以body可以直接写中文。但要注意，如果一条短信超过160个英文字符（中文短信的每条限制通常按字数和编码算，一般70个中文字符算一条），Twilio会自动把消息拆分成多条并分别计费。比如一段300字的中文消息，实际会被拆成5条计费。你收到的是5条连续的短信，费用也是5份。

为了避免成本失控，我认为在业务层就要控制body长度。可以写一个简单的截断函数：

MAX_BODY_LENGTH = 70 def truncate_body(text, max_len=MAX_BODY_LENGTH): if len(text) <= max_len: return text return text[:max_len-3] + "..."

注意，截断时不要按字节截取，Python的len默认统计的是字符数，中文没问题，但如果你混合了emoji或者特殊符号，最好先做text.encode('utf-16')之类的编码长度检查，避免某些代理端出现乱码。我在生产里就遇到过emoji把长度计算搞错，导致消息被硬截断，通知内容变成了乱码。后来统一先按字符数限制，再做一个编码安全验证：

def safe_text(text, max_utf16_units=155): encoded = text.encode("utf-16") if len(encoded) <= max_utf16_units * 2: return text # 逐字符缩减直到安全 while len(text) > 0 and len(text.encode("utf-16")) > max_utf16_units * 2: text = text[:-1] return text.rstrip() + "..."

3.4 重构为可复用的发送模块

不要把所有代码堆在一个脚本里，后面维护会想哭。我的一般做法是建一个sms.py，里面封装一个send_sms函数：

from typing import Optional from twilio.rest import Client from twilio.base.exceptions import TwilioRestException from .settings import ... client = Client(account_sid, auth_token) def send_sms( to: str, body: str, from_: Optional[str] = None, status_callback: Optional[str] = None, ) -> str: from_ = from_ or TWILIO_PHONE_NUMBER body = safe_text(body) try: message = client.messages.create( to=to, from_=from_, body=body, status_callback=status_callback, ) return message.sid except TwilioRestException as e: # 记录日志，抛业务自定义异常或返回None logger.error("Twilio发送失败: code=%s message=%s", e.code, e.msg) raise

这里有几个关键点：

• status_callback参数可以传入一个URL，Twilio会把短信状态事件（sent、delivered、failed）POST到这个URL，我们后续接收状态就靠它。
• 使用TwilioRestException捕获SDK抛出的异常，比直接全量except Exception更精确，方便区分是参数错误、余额不足还是号码无效。
• 函数返回message SID，业务层可以拿这个SID去轮询状态或者记录日志。

3.5 批量发送与并发控制

如果业务需要一次性给多个人发通知，直接循环调用send_sms是最简单的，但效率不高，因为每个请求都要等待网络往返。可以用线程池并发发送，同时对Twilio限制要心里有数：默认每个电话号码每秒最多发1条消息，如果短时间内大量发送，可能撞上ThrottleException。

我写的并发代码长这样：

from concurrent.futures import ThreadPoolExecutor, as_completed def send_to_many(targets: list[str], body: str, max_workers=5): results = [] with ThreadPoolExecutor(max_workers=max_workers) as executor: futures = {executor.submit(send_sms, target, body): target for target in targets} for future in as_completed(futures): target = futures[future] try: sid = future.result() results.append((target, sid, "success")) except Exception as e: results.append((target, None, str(e))) return results

注意并发度为5就够了，不要开几十个线程去打Twilio接口，一是容易触发限流，二是对你的服务器也没有好处。另外，发送频率控制建议在应用层再加一个限速器，例如用threading.Semaphore或者简单的信号量控制每秒最多发出的消息数。

4. 实战场景：把短信系统接到真实业务里

4.1 场景一：服务器监控告警

假设你有一台Linux服务器，想监控CPU和磁盘占用率，超过阈值就发短信提醒自己。用Python写一个监控脚本，采集系统指标，调用封装好的短信模块。

最简单的方式是读取/proc/stat和/proc/diskstats，但在脚本示例里，用psutil库更省事：

import psutil from sms import send_sms THRESHOLD_CPU = 85 THRESHOLD_DISK = 90 cp = psutil.cpu_percent(interval=1) disk = psutil.disk_usage("/").percent alerts = [] if cp > THRESHOLD_CPU: alerts.append(f"CPU使用率 {cp}% 超过阈值 {THRESHOLD_CPU}%") if disk > THRESHOLD_DISK: alerts.append(f"磁盘使用率 {disk}% 超过阈值 {THRESHOLD_DISK}%") if alerts: body = "服务器告警\n" + "\n".join(alerts) send_sms("+8613800138000", body)

这个脚本可以放进crontab，每5分钟执行一次。为了避免重复告警轰炸，我建议在脚本里加一个“静默期”机制：同一指标的首次告警发送短信，之后只有在恢复或超过静默时间后才再次发送。可以用一个简单的时间戳文件记录上次告警时间，比较当前时间和静默期。

用Twilio做告警还有一个好处：你可以顺便把状态回调接上，如果短信没送达（比如手机欠费停机），系统还能触发备用通道，比如电话呼叫或邮件。不过那是进阶玩法了。

4.2 场景二：定时提醒与每日汇报

很多时候短信不是“异常触发”，而是“定时推送”。比如每天早上9点把昨天的订单数、销售额汇总发到你手机上。

用APScheduler库可以同时管理多个定时任务：

pip install apscheduler

核心示例：

from apscheduler.schedulers.blocking import BlockingScheduler from datetime import datetime from sms import send_sms def job_daily_report(): now = datetime.now().strftime("%Y-%m-%d %H:%M") body = f"【每日汇总】{now}\n昨日订单: 126\n销售额: ￥35,800" send_sms("+8613800138000", body) scheduler = BlockingScheduler() scheduler.add_job(job_daily_report, "cron", hour=9, minute=0) scheduler.start()

BlockingScheduler会阻塞主线程，适合独立脚本。如果集成到Web服务里，应该用BackgroundScheduler并妥善管理生命周期。另外，在写耗时长的定时任务时，要把短信发送放在任务最后，避免任务超时导致短信晚发或漏发。

4.3 场景三：验证码发送与过期控制

短信验证码是另一类高频应用。虽然Twilio也能直接发OTP，但业务逻辑得你自己写。一般的流程：生成6位随机码，存到Redis/数据库，设置5分钟过期，然后调用短信接口发送给用户，用户提交后校验。

代码示例（伪代码结构）：

import random from sms import send_sms from redis import Redis r = Redis(...) def send_verify_code(phone: str): code = f"{random.randint(0, 999999):06d}" r.setex(f"verify:{phone}", 300, code) body = f"你的验证码是 {code}，5分钟内有效。" send_sms(phone, body)

这里有三个容易踩的坑：

• 验证码生成必须用安全随机源，random.randint在低安全要求下可用，但如果做高并发抢码攻击，建议用secrets模块。
• 同一个手机号短时间内不能频繁发，A2P/短信防垃圾策略一般要求至少60秒间隔，否则可能被运营商屏蔽。最好在发送前检查一下Redis里有没有“发送冷却”标记。
• 验证码短信的文案要和常规短信区分，不要带营销词汇，避免被误标为营销短信。

4.4 场景四：状态回调用Webhook接收送达报告

短信状态回执是生产系统最容易被忽略的模块。Twilio在消息状态变化时，会向status_callback指定的URL发送POST请求，事件包括queued、sent、delivered、failed等。

假设我们用Flask搭建一个轻量接口：

from flask import Flask, request from twilio.twiml.messaging_response import MessagingResponse app = Flask(__name__) @app.route("/sms/status", methods=["POST"]) def status_callback(): message_sid = request.form.get("MessageSid") status = request.form.get("MessageStatus") error_code = request.form.get("ErrorCode") # 写入数据库或者日志 print(f"消息 {message_sid} 状态: {status}, 错误码: {error_code}") return "OK", 200

这里有个安全点：必须验证Twilio请求的签名，否则任何人都可以伪造状态推送到你接口。Twilio提供了twilio.request_validator，用法是：

from twilio.request_validator import RequestValidator validator = RequestValidator(TWILIO_AUTH_TOKEN) url = "https://你的域名/sms/status" signature = request.headers.get("X-Twilio-Signature") if not validator.validate(url, request.form, signature): abort(403)

再说一个细节：status_callback参数建议在创建消息时就传上，Twilio会在这个URL中不断更新状态。如果你用Messaging Service，也可以在Console中统一配置Status Callback URL，不必须在代码里传。

4.5 场景五：批量营销通知的合规化处理

如果你拿这套系统给用户批量发营销短信，比如“双十一全场8折”，需要注意几点：

• 收款方必须有用户授权，即“您同意接收营销短信”。Twilio会要求做A2P 10DLC注册，否则发送美国号码会被拒绝或增加高额罚金。
• 文案中必须包含退订方式，比如回复STOP取消。Twilio会自动处理STOP关键词并将号码加入黑名单。
• 我见过很多人在开发阶段用真实手机号测试营销文案，结果被Twilio标记号码，之后连事务性短信也发不出去了。营销短信和事务性短信最好分开使用不同的号码和Messaging Service。

5. 常见问题与排查技巧实录

这里有我在实际开发中碰到的高频问题，列一张速查表给读者参考。

5.1 为什么发不出或收不到短信？

这一类问题排在首位的原因是网络环境复杂。Twilio的API在国内网络下访问不算稳定，如果代码部署在国内服务器直连Twilio，偶尔会超时。我试过用超时重试机制解决，给Client配置http_client，增加超时时间：

from twilio.http.http_client import TwilioHttpClient http_client = TwilioHttpClient(timeout=30) client = Client(account_sid, auth_token, http_client=http_client)

但最好是使用企业级代理或走云上出口，不过这个不在本文范围内，大家知道有风险就行。

另一个常见问题是收件人号码是否填写正确。Twilio要求号码必须是E.164格式，比如美国号码是+14155552671，中国号码是+8613800138000。很多新手写成13800138000，没有国家区号，Twilio直接报号码不存在。

5.2 中文短信的签名、退订和识别

你是不是也遇到过这样的情况：短信收到了，但是手机系统自动折叠进“营销短信”，或者被标记为“未知号码”？这是因为Twilio发送短信时，会根据号码的国家和类型自动分配发送者标识（Sender ID）。在中国，发送者ID通常是随机号码或106开头的一长串，没有传统意义的“短信签名”——大家都在用的“【XX云】”那种形式，Twilio并不支持。

所以在用Twilio给国内用户发短信时，文案开头最好加一个自定义的“品牌标识”，比如【我的笔记】，让用户一眼看出来是谁发的。否则容易被打上“垃圾”标签。同时文案必须清楚提供退订方式，比如“回复T退订”，否则被用户投诉多了，号码可能被封。

5.3 费用控制：明明没发几条，账单却不少

Twilio的计费是按“段”算的，而不是按“条”算。前面说过，一条超过160字符的短信会被拆成多段，每段单独计费。所以你写了一条500字的中文“通知”，实际会被计成8条短信的价格。如果你每条都动态拼接一堆变量且不做长度控制，月底账单会吓你一跳。

我建议给自己的发送函数加一个“预估段数”的日志：

def estimate_segments(body): utf16_len = len(body.encode("utf-16")) // 2 if utf16_len <= 160: return 1 gsm7_len = len(body.encode("gsm0338")) # 只对纯英文等有效 # 简化：中文按70字符一段 return math.ceil(utf16_len / 70)

每次发送前打印预估段数，让费用透明化。另外Twilio后台有Usage菜单，可以按日期、号码、消息类型查看详细消费，定期检查一下还是很有必要的。

5.4 Twilio的测试模式与模拟响应

本地开发时不想真的发短信怎么办？Twilio提供了测试的认证Token，用测试凭证创建Client后，API会返回模拟的消息SID，不会真的产生费用，也不会真的发出短信。你可以在Console的API Keys页面生成测试密钥，以AC...和SK...开头的测试Key就是测试模式。

但注意测试模式下message.sid是有规律的SM...deadbeef...，方便你识别。我做单元测试时基本都用这个模式，能覆盖发送流程的日志和异常分支，但无法验证真实运营商逻辑。真正要测试端到端，还是需要升级账号发一条人民币0.0几元的短信，这个成本不要省。

6. 落地过程中的几点私人心得

说实话，这个项目本身不算难，难点都在“细节”。比如环境变量别暴露、短信长度别超、状态回调别漏、限流要控制。我在自己项目里踩过一次最深的坑，是从Twilio的试用账号切到付费账号后，忘了把.env里的测试密钥换成正式密钥，结果上线后所有短信都显示“发送成功”但实际上一条都没发出去——完全是因为测试Token不会真正投递。直到用户问“怎么没收到验证码”才排查出来。所以在你切换环境之后，第一件事就是先给自己发一条测试短信，确认真实链路通了再继续。

另外一个小技巧：把twilio.rest.Client初始化为全局单例，不要每次发送都新建实例。SDK底层维护了连接池，全局复用能明显减少延迟。如果你用线程池并发发送，注意Client是线程安全的，放心用。

最后再提一句扩展性：如果你以后想把短信服务从Twilio换到其他云厂商，最好在项目初期就抽象出统一的发短信接口，比如SmsProvider类，把Twilio的实现放在接口后面。这样迁移时只需要替换一个实现类，业务层一点不用动。我在实际经历过一次从Twilio迁移到国内平台后，才真正体会到接口抽象的价值，等到业务量大了再改成本极高，前期花10分钟设计，后面能帮你省下很多个加班夜晚。

如果你也有正在运行的Python服务，不妨现在就把这个短信通知系统接进去。哪怕只是先写一个脚本，等半夜服务器告警短信吵醒你一次，你就会明白这套东西到底值不值得做。