1. 项目整体拆解从需求到落地的一整套思路先把这个项目的本质说清楚用 Python 写一套调度逻辑在满足特定条件时调用 Twilio 的短信 API把一条预设好的消息发到指定手机号上。听起来很简单但真正做起来你会发现里面埋着不少坑——API 调用失败怎么重试、手机号格式怎么处理、定时任务怎么不重复触发、敏感信息怎么存储这些才是决定项目能不能用、敢不敢上线的东西。我自己做这个项目的起因很俗每周要手动给几个固定的人发提醒消息不是工作安排就是账单到期经常忙起来就忘。写个脚本用 Twilio 发短信把重复劳动自动化掉这是最直接的动机。后来做着做着发现这套东西可以扩展成告警通知、服务监控提醒、每日定时播报甚至是你家智能设备的通知中继。从我拆解需求的角度看这个项目其实由四个独立模块组成业务触发层什么条件下要发短信。可以是定时任务、某个 HTTP 请求触发、或者某个系统监控指标超标。消息组装层短信内容从哪里来动态参数怎么拼装要不要支持模板。发送层调用 Twilio API 发短信处理回调、重试、结果记录。配置与运维层手机号、API Key、模板内容这些不能写死在代码里要用环境变量或配置文件。对于刚接触的人我建议不要一上来就追求花哨先把一个最简单的定时发送固定内容跑通再去加各种功能。原因后面细讲但核心是你只有先打通整条链路才能知道每个环节的坑长什么样。2. 为什么选 Python 和 Twilio而不是别的方案2.1 Twilio 在短信发送里的位置短信发送这件事本身有很强的门槛。个人开发者没有运营商通道没法直接通过命令行发短信必须依赖短信服务商。国内的短信服务商不少但国际通用的、文档友好、还有免费试用额度的Twilio 是绕不开的一个选择。Twilio 提供的是 HTTP API你把收件人号码、发件号码、消息内容发给它的接口它负责通过运营商网络把短信送到用户手机。对开发者来说不用关心短信网关协议只需要处理 HTTP 请求和响应。它有几个特点很戳我有免费试用额度新注册账号会送一笔测试余额够你跑通几百条测试短信。开发文档完善Python 官方库更新及时你不会遇到文档跟 SDK 版本对不上这种低级问题。消息发送状态可追踪能查询每条短信是已发送、已送达还是发送失败这个特性在做重试和排查时非常有用。2.2 Python 在这类任务里的优势Python 做这种脚本级应用几乎是本能选择。它有 requests、Twilio SDK、APScheduler 这类现成库不用自己造轮子语法简洁逻辑清晰出问题好调试而且部署方便一个 Python 文件加一个 Cron 任务就能跑起来。有人可能会问用 Node.js 或 Go 不行吗当然行。但如果你只是做个人通知工具、小规模告警Python 的生态和上手成本是最平衡的。2.3 方案选型对比我做了一个对比表格方便你理解为什么最终选了这套组合方案优点缺点适用场景Python Twilio开发快、文档全、免费额度够用长期大量发送成本高个人通知、小规模监控告警原生短信网关费用低、完全可控需要对接运营商、资质麻烦企业级大规模发送国内短信服务商国内送达率高、资质规范一般需要企业认证、测试不便面向国内用户的验证码与营销短信邮件/IM通知替代免费、实现简单到达率和实时性不如短信非紧急通知场景从这个表能看出来Python Twilio 不是万能的但在个人项目、快速落地、低成本验证这个场景下是最舒服的。3. 环境准备与前置条件先把环境搭好再做具体功能。我推荐使用虚拟环境管理 Python 依赖避免污染系统环境。下面每一步我都说说我怎么做的以及为什么要这么做。3.1 准备一个虚拟环境虚拟环境的作用是把项目依赖隔离在一个独立目录里不同项目之间不会打架。尤其你同时开发多个 Python 项目时没有虚拟环境就是灾难现场。创建和激活虚拟环境的命令如下# 创建虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate激活后你会在终端提示符前面看到(venv)字样。后续所有pip install都会装到这个环境里。注意Windows 系统的激活命令是venv\Scripts\activatemacOS 和 Linux 是上面的写法。别在 Windows 上敲source venv/bin/activate会报错找不到路径。3.2 安装 Twilio Python SDKTwilio 官方提供 Python SDK安装非常直接pip install twilio它会顺带装上requests等依赖库。你不需要单独安装 requests因为 twilio 包内部已经在用了。3.3 获取 Twilio 凭据Twilio 的凭据分两部分Account SID 和 Auth Token。SID 是账号标识Token 是访问密钥。这两个值在你的 Twilio 控制台首页可以看到。拿到这个信息后我建议第一时间写入环境变量而不是写死在代码里。原因有两个一是代码会提交到 GitHub泄露密钥等于把账号送人二是环境变量可以在不同环境中切换本地测试、线上运行互不影响。设置环境变量的方式export TWILIO_ACCOUNT_SID你的SID export TWILIO_AUTH_TOKEN你的Token export TWILIO_FROM_NUMBER你的Twilio号码 export ALERT_TO_NUMBER你要通知的手机号在 Windows PowerShell 中对应写法$env:TWILIO_ACCOUNT_SID 你的SID $env:TWILIO_AUTH_TOKEN 你的Token3.4 购买和配置 Twilio 号码在 Twilio 控制台里可以挑选一个支持短信的号码它自带每月一定的短信配额按用量计费。选号时注意选择支持短信SMS能力的号码有些号段只有语音能力。你还需要在控制台里配置消息回调 URL这样 Twilio 才能把短信发送状态回调到你的服务器。如果没有公网服务器可以先跳过回调用查询接口主动获取状态。4. 核心功能实现发送单条短信4.1 最小化发送代码先写一个最简单的发送函数。这个函数只做一件事给指定号码发一条内容固定的短信。from twilio.rest import Client import os # 从环境变量读取凭据 account_sid os.environ[TWILIO_ACCOUNT_SID] auth_token os.environ[TWILIO_AUTH_TOKEN] from_number os.environ[TWILIO_FROM_NUMBER] client Client(account_sid, auth_token) def send_sms(to_number, body): message client.messages.create( toto_number, from_from_number, bodybody ) print(f消息SID: {message.sid}) return message.sid if __name__ __main__: to_number os.environ[ALERT_TO_NUMBER] send_sms(to_number, 这是一条测试短信。)执行后如果看到打印的 SID说明发送成功。如果没收到短信去 Twilio 控制台的日志页面查看具体错误。4.2 号码格式那些事儿Twilio 对号码格式要求比较严格必须使用 E.164 格式国家代码 完整号码比如中国的号码要写成86xxxxxxxxxxx。很多人第一次用就栽在这里明明本地号码是13800138000直接传进去Twilio 返回错误。解决方式很简单发送前做一次格式化检查。我习惯用一个函数统一处理号码def normalize_phone_number(number, country_code86): # 去掉空格、横线、括号 cleaned number.replace( , ).replace(-, ).replace((, ).replace(), ) if cleaned.startswith(): return cleaned if cleaned.startswith(country_code): return cleaned if cleaned.startswith(0): cleaned cleaned[1:] # 去掉前导零 return country_code cleaned这个函数不算完美但能覆盖大多数场景。我测试敏感情形时会额外校验cleaned.isdigit()。4.3 发送状态与异常处理Twilio SDK 的发送方法并不会保证短信一定送达。它会返回消息对象但发送是异步的真正的状态变化会通过回调或查询接口反映。所以异常处理要分层HTTP 异常网络不通、认证失败、号码非法这类问题需要当场处理。业务异常号码被屏蔽、消息内容违规、余额不足这类需要记录并告警。状态异常发送后显示 failed 或 undelivered需要根据回调状态做处理。我在代码里把异常记录到日志文件方便事后排查import logging from twilio.base.exceptions import TwilioRestException logging.basicConfig( filenamesms_notifier.log, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s ) def safe_send(to_number, body): try: sid send_sms(to_number, body) logging.info(f发送成功 to{to_number} sid{sid}) return sid except TwilioRestException as e: logging.error(fTwilio错误 code{e.code} msg{e.msg}) raise except Exception as e: logging.error(f未知错误 {e}) raise把日志预留好后面排查问题时你会感谢自己。5. 进阶功能定时任务与动态消息5.1 用 APScheduler 做定时调度定时任务是短信通知系统最常见的需求。你可以选择系统 Cron也可以用 Python 里的 APScheduler 库统一管理。我推荐 APScheduler因为它的调度规则更灵活而且能直接集成到你的 Python 项目里不用依赖系统环境。安装pip install apscheduler一个每分钟执行一次的任务可以这么写from apscheduler.schedulers.blocking import BlockingScheduler scheduler BlockingScheduler() def job(): body 定时提醒该喝水了。 to_number os.environ[ALERT_TO_NUMBER] safe_send(to_number, body) # 在每天上午9点执行 scheduler.add_job(job, CronTrigger, hour9, minute0, idmorning_remind) scheduler.start()CronTrigger 支持非常丰富的规则hour9, minute30代表每天 9:30day_of_weekmon-fri代表周一到周五hour9-18, minute*/15代表 9 点到 18 点每 15 分钟一次。这些规则记不住没关系用的时候查文档就行。5.2 动态参数拼装消息固定内容只能算 hello world真正用得上的消息往往包含动态数据。比如每天的最高温度、股票收盘价、服务器负载。这些数据可以从 API、数据库或爬虫获取。我写了一个简单的数据来源模拟从本地 JSON 文件读取内容拼接到短信里。import json def load_payload(): with open(report.json, r, encodingutf-8) as f: data json.load(f) return data def build_message(data): return f【日报】今日完成 {data[completed_tasks]} 项任务新增 {data[new_tasks]} 项待办。 def job(): data load_payload() body build_message(data) to_number os.environ[ALERT_TO_NUMBER] safe_send(to_number, body)模板字符串用 f-string 或者 format 都行。需要注意短信有长度限制单条短信通常 160 个字符。超过 160 字符 Twilio 会自动拆成多条并按多条计费。我的建议是保持正文简短把重要的信息放前面这样即使被截断也能传达关键内容。5.3 避免重复触发导致重复发送定时任务最常见的操作失误是调度器在应用重启后重复执行积压的任务。APScheduler 默认行为是启动时不会执行之前错过的任务但它支持misfire_grace_time参数来控制容错窗口。如果你的任务本身应该保证不能被跳过比如每分钟读取一次传感器数据那不用太担心。但如果是每天一次的报表万一调度器因为网络问题停了 5 分钟你肯定希望它恢复后先补发上一次的。这时可以设置scheduler.add_job( job, CronTrigger, hour9, minute0, iddaily_report, misfire_grace_time3600, coalesceTrue )misfire_grace_time表示任务原定执行时间之后最多延迟多久仍然执行。coalesceTrue表示如果错过了多次调度只执行最后一次。这两个参数对于生产环境非常重要避免短信轰炸。6. 工程化改造配置管理与模块拆分项目一旦开始变大所有代码堆在一个文件里就会变成维护噩梦。我参照自己的其他项目经验把这个小系统拆成了三个模块。6.1 目录结构sms-notifier/ ├── venv/ # 虚拟环境 ├── config.py # 配置读取 ├── sms_sender.py # 发送逻辑 ├── scheduler_jobs.py # 定时任务 ├── data/ │ └── report.json # 动态数据源 ├── logs/ │ └── sms_notifier.log # 运行日志 └── requirements.txt # 依赖清单6.2 config.py 示例统一管理配置避免在业务代码里到处读取环境变量import os class Config: ACCOUNT_SID os.environ[TWILIO_ACCOUNT_SID] AUTH_TOKEN os.environ[TWILIO_AUTH_TOKEN] FROM_NUMBER os.environ[TWILIO_FROM_NUMBER] ALERT_TO_NUMBER os.environ[ALERT_TO_NUMBER] LOG_FILE os.path.join(os.path.dirname(__file__), logs, sms_notifier.log)6.3 sms_sender.py 示例把发送逻辑封装成类方便复用和测试import logging from twilio.rest import Client from twilio.base.exceptions import TwilioRestException from config import Config class SmsSender: def __init__(self): self.client Client(Config.ACCOUNT_SID, Config.AUTH_TOKEN) self.from_number Config.FROM_NUMBER logging.basicConfig( filenameConfig.LOG_FILE, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s ) def send(self, to_number, body): try: message self.client.messages.create( toto_number, from_self.from_number, bodybody ) logging.info(fsend ok to{to_number} sid{message.sid}) return message.sid except TwilioRestException as e: logging.error(ftwilio error code{e.code} msg{e.msg}) raise7. 监控与自定义告警让系统更有实用价值定时提醒只是最基础的使用场景。一旦把这个系统理解成通知通道你会发现它能干的活非常多。我自己在项目中用得最顺手的是服务监控告警。7.1 健康检查与告警假设你有一个 Web 服务你希望它在宕机时及时发短信通知你。那你需要写一个探活函数定时检查服务的 HTTP 状态码。import requests from sms_sender import SmsSender import time sender SmsSender() def check_service_health(): url http://你的服务地址/health try: resp requests.get(url, timeout5) if resp.status_code 500: sender.send(Config.ALERT_TO_NUMBER, f服务异常HTTP {resp.status_code}) else: print(服务正常) except requests.RequestException: sender.send(Config.ALERT_TO_NUMBER, 服务无法访问请检查进程是否存活。)这里要注意一个细节检查频率不能太高否则故障恢复前会持续发送大量短信。我通常会加一个简单的状态标记只有状态改变时才发通知。7.2 持续性故障中的降噪机制降噪机制可以这样做记录上一次状态如果当前状态与上次相同并且上次已经发过通知就跳过发送。这样服务虽然持续异常但你只会在状态变化的那一刻收到一条短信。用一个模块级变量或小文件来存储状态即可last_status_file last_status.txt def read_last_status(): try: with open(last_status_file, r) as f: return f.read().strip() except FileNotFoundError: return unknown def write_last_status(status): with open(last_status_file, w) as f: f.write(status)这个小小的技巧能让你的短信条数和费用都大幅下降而且也不会因为短信轰炸让你把通知功能关掉。7.3 消息内容的最佳实践短信内容不是随便写写就发出去的。从实际使用效果看一条好的通知短信应该包含是谁、什么事件、严重级别、怎么处理四要素。比如下面这两条对比普通写法服务异常好一点的写法【监控告警】服务A在2025-01-20 14:33:22发生故障错误码500连续失败3次请立即处理。我发现很多初学者写通知短信时只写出错啦等真正收到短信完全想不起来是哪个服务、出了什么事。别偷懒把关键信息拼进去。8. 常见问题与排查技巧实录这个项目看着不起眼但实操中问题非常多。我基本都踩过整理出来给你参考。8.1 发送失败错误码 21408这个错误代表你的 Twilio 号码没有短信权限或者号码与短信功能不匹配。解决方法是去控制台重新选一个支持短信的号码并确认该号码已启用短信能力。8.2 收不到短信但接口返回成功遇到这种情况先别怀疑 API大概率是号码格式问题或者运营商延迟。先查消息状态在 Twilio 控制台或通过 API 查询 message.sid 的状态。如果状态是delivered说明运营商已送达如果状态是undelivered可能是目标手机拒收或内容被过滤。8.3 认证失败错误码 20003这个错误很直白就是 Auth Token 配错了或者 SID 填的别人的。检查环境变量是否正确还要注意不要有空格和换行符。我自己的环境变量文件偶尔会因为复制粘贴多了一个空格排查了半天才发现。8.4 时区问题定时任务默认使用服务器本地时区。如果你部署在云服务器上系统时区不一定是北京时间可能导致任务在错误的时间触发。在创建 CronTrigger 时指定时区from apscheduler.triggers.cron import CronTrigger from pytz import timezone trigger CronTrigger(hour9, minute0, timezonetimezone(Asia/Shanghai))8.5 内存泄漏和日志增长长时间运行的调度任务要注意日志文件增长。logging 默认会无限制追加时间长了磁盘会被打满。加一个简单的 RotatingFileHandlerfrom logging.handlers import RotatingFileHandler handler RotatingFileHandler(sms_notifier.log, maxBytes5*1024*1024, backupCount2)这样单个日志超过 5MB 会自动轮转。8.6 快速自查速查表现象可能原因排查位置收到错误 21408号码短信权限未开启控制台号码配置接口返回成功但没收到短信号码格式错误/状态为失败查询消息状态认证失败SID/Token 错误环境变量定时任务不触发时区/调度器未启动检查日志走时重复收到短信调度任务重复注册检查 add_job 调用次数9. 实战经验与心得9.1 从零搭建的最短路径如果你正准备照着做我给你一条最短路径注册 Twilio拿免费额度。购买或试用一个支持短信的号码。创建虚拟环境安装 twilio。跑通最小发送代码。加入定时任务。加入异常处理和日志。推送到 GitHub但务必使用.gitignore忽略虚拟目录和日志文件。9.2 一个小建议先用假的发送逻辑测试我在真正对接 Twilio 之前会先用一个假的发送函数来测试整个调度逻辑是否正确。这样既省短信费又避免把测试短信发到真实手机号上。# mock_sender.py def send(to_number, body): print(f[MOCK] 发送到 {to_number}: {body}) return mock-sid把sms_sender.py导入的地方替换成mock_sender.py等测完调度流程再换回真实 SDK。这个习惯帮我节省了很多多余的短信条数。9.3 关于成本控制Twilio 的计费是按条数和目的地费率来的。发到中国大陆的短信费率不算低所以控制成本的方法就是减少发送量。我已经在降噪机制上做了优化再一个就是不要用短信用来发营销内容它天生适合的是高频低延迟的通知。要发广告请去找营销短信供应商。9.4 这个系统还能怎么扩展我在原有代码基础上给项目加过几个扩展点很容易往里面塞功能Webhook 接口用 Flask 写一个 HTTP 接口接收 JSON 数据后触发短信发送这样其他系统可以调接口发短信。告警模板把内容模板放到单独文件里支持占位符替换。多收件人传一个号码列表循环发送注意每个收件人之间加错误隔离。状态回写通过 Twilio 回调接口更新数据库记录每条短信的最终状态。最终你得到的不仅是一个发短信小程序而是一个真正可复用的通知中心。我在实际使用中最满意的一点就是这套系统晚上静默运行第二天醒来手机里已经有需要的提醒。它不需要我盯着不会再因为忙忘事。踩过几次坑之后我现在更看重它的稳定性——不发错、不漏发、不重复发比任何花哨功能都重要。如果你也打算做类似的东西建议先把这一层打磨好。
1. 项目整体拆解从需求到落地的一整套思路先把这个项目的本质说清楚用 Python 写一套调度逻辑在满足特定条件时调用 Twilio 的短信 API把一条预设好的消息发到指定手机号上。听起来很简单但真正做起来你会发现里面埋着不少坑——API 调用失败怎么重试、手机号格式怎么处理、定时任务怎么不重复触发、敏感信息怎么存储这些才是决定项目能不能用、敢不敢上线的东西。我自己做这个项目的起因很俗每周要手动给几个固定的人发提醒消息不是工作安排就是账单到期经常忙起来就忘。写个脚本用 Twilio 发短信把重复劳动自动化掉这是最直接的动机。后来做着做着发现这套东西可以扩展成告警通知、服务监控提醒、每日定时播报甚至是你家智能设备的通知中继。从我拆解需求的角度看这个项目其实由四个独立模块组成业务触发层什么条件下要发短信。可以是定时任务、某个 HTTP 请求触发、或者某个系统监控指标超标。消息组装层短信内容从哪里来动态参数怎么拼装要不要支持模板。发送层调用 Twilio API 发短信处理回调、重试、结果记录。配置与运维层手机号、API Key、模板内容这些不能写死在代码里要用环境变量或配置文件。对于刚接触的人我建议不要一上来就追求花哨先把一个最简单的定时发送固定内容跑通再去加各种功能。原因后面细讲但核心是你只有先打通整条链路才能知道每个环节的坑长什么样。2. 为什么选 Python 和 Twilio而不是别的方案2.1 Twilio 在短信发送里的位置短信发送这件事本身有很强的门槛。个人开发者没有运营商通道没法直接通过命令行发短信必须依赖短信服务商。国内的短信服务商不少但国际通用的、文档友好、还有免费试用额度的Twilio 是绕不开的一个选择。Twilio 提供的是 HTTP API你把收件人号码、发件号码、消息内容发给它的接口它负责通过运营商网络把短信送到用户手机。对开发者来说不用关心短信网关协议只需要处理 HTTP 请求和响应。它有几个特点很戳我有免费试用额度新注册账号会送一笔测试余额够你跑通几百条测试短信。开发文档完善Python 官方库更新及时你不会遇到文档跟 SDK 版本对不上这种低级问题。消息发送状态可追踪能查询每条短信是已发送、已送达还是发送失败这个特性在做重试和排查时非常有用。2.2 Python 在这类任务里的优势Python 做这种脚本级应用几乎是本能选择。它有 requests、Twilio SDK、APScheduler 这类现成库不用自己造轮子语法简洁逻辑清晰出问题好调试而且部署方便一个 Python 文件加一个 Cron 任务就能跑起来。有人可能会问用 Node.js 或 Go 不行吗当然行。但如果你只是做个人通知工具、小规模告警Python 的生态和上手成本是最平衡的。2.3 方案选型对比我做了一个对比表格方便你理解为什么最终选了这套组合方案优点缺点适用场景Python Twilio开发快、文档全、免费额度够用长期大量发送成本高个人通知、小规模监控告警原生短信网关费用低、完全可控需要对接运营商、资质麻烦企业级大规模发送国内短信服务商国内送达率高、资质规范一般需要企业认证、测试不便面向国内用户的验证码与营销短信邮件/IM通知替代免费、实现简单到达率和实时性不如短信非紧急通知场景从这个表能看出来Python Twilio 不是万能的但在个人项目、快速落地、低成本验证这个场景下是最舒服的。3. 环境准备与前置条件先把环境搭好再做具体功能。我推荐使用虚拟环境管理 Python 依赖避免污染系统环境。下面每一步我都说说我怎么做的以及为什么要这么做。3.1 准备一个虚拟环境虚拟环境的作用是把项目依赖隔离在一个独立目录里不同项目之间不会打架。尤其你同时开发多个 Python 项目时没有虚拟环境就是灾难现场。创建和激活虚拟环境的命令如下# 创建虚拟环境 python3 -m venv venv # 激活虚拟环境 source venv/bin/activate激活后你会在终端提示符前面看到(venv)字样。后续所有pip install都会装到这个环境里。注意Windows 系统的激活命令是venv\Scripts\activatemacOS 和 Linux 是上面的写法。别在 Windows 上敲source venv/bin/activate会报错找不到路径。3.2 安装 Twilio Python SDKTwilio 官方提供 Python SDK安装非常直接pip install twilio它会顺带装上requests等依赖库。你不需要单独安装 requests因为 twilio 包内部已经在用了。3.3 获取 Twilio 凭据Twilio 的凭据分两部分Account SID 和 Auth Token。SID 是账号标识Token 是访问密钥。这两个值在你的 Twilio 控制台首页可以看到。拿到这个信息后我建议第一时间写入环境变量而不是写死在代码里。原因有两个一是代码会提交到 GitHub泄露密钥等于把账号送人二是环境变量可以在不同环境中切换本地测试、线上运行互不影响。设置环境变量的方式export TWILIO_ACCOUNT_SID你的SID export TWILIO_AUTH_TOKEN你的Token export TWILIO_FROM_NUMBER你的Twilio号码 export ALERT_TO_NUMBER你要通知的手机号在 Windows PowerShell 中对应写法$env:TWILIO_ACCOUNT_SID 你的SID $env:TWILIO_AUTH_TOKEN 你的Token3.4 购买和配置 Twilio 号码在 Twilio 控制台里可以挑选一个支持短信的号码它自带每月一定的短信配额按用量计费。选号时注意选择支持短信SMS能力的号码有些号段只有语音能力。你还需要在控制台里配置消息回调 URL这样 Twilio 才能把短信发送状态回调到你的服务器。如果没有公网服务器可以先跳过回调用查询接口主动获取状态。4. 核心功能实现发送单条短信4.1 最小化发送代码先写一个最简单的发送函数。这个函数只做一件事给指定号码发一条内容固定的短信。from twilio.rest import Client import os # 从环境变量读取凭据 account_sid os.environ[TWILIO_ACCOUNT_SID] auth_token os.environ[TWILIO_AUTH_TOKEN] from_number os.environ[TWILIO_FROM_NUMBER] client Client(account_sid, auth_token) def send_sms(to_number, body): message client.messages.create( toto_number, from_from_number, bodybody ) print(f消息SID: {message.sid}) return message.sid if __name__ __main__: to_number os.environ[ALERT_TO_NUMBER] send_sms(to_number, 这是一条测试短信。)执行后如果看到打印的 SID说明发送成功。如果没收到短信去 Twilio 控制台的日志页面查看具体错误。4.2 号码格式那些事儿Twilio 对号码格式要求比较严格必须使用 E.164 格式国家代码 完整号码比如中国的号码要写成86xxxxxxxxxxx。很多人第一次用就栽在这里明明本地号码是13800138000直接传进去Twilio 返回错误。解决方式很简单发送前做一次格式化检查。我习惯用一个函数统一处理号码def normalize_phone_number(number, country_code86): # 去掉空格、横线、括号 cleaned number.replace( , ).replace(-, ).replace((, ).replace(), ) if cleaned.startswith(): return cleaned if cleaned.startswith(country_code): return cleaned if cleaned.startswith(0): cleaned cleaned[1:] # 去掉前导零 return country_code cleaned这个函数不算完美但能覆盖大多数场景。我测试敏感情形时会额外校验cleaned.isdigit()。4.3 发送状态与异常处理Twilio SDK 的发送方法并不会保证短信一定送达。它会返回消息对象但发送是异步的真正的状态变化会通过回调或查询接口反映。所以异常处理要分层HTTP 异常网络不通、认证失败、号码非法这类问题需要当场处理。业务异常号码被屏蔽、消息内容违规、余额不足这类需要记录并告警。状态异常发送后显示 failed 或 undelivered需要根据回调状态做处理。我在代码里把异常记录到日志文件方便事后排查import logging from twilio.base.exceptions import TwilioRestException logging.basicConfig( filenamesms_notifier.log, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s ) def safe_send(to_number, body): try: sid send_sms(to_number, body) logging.info(f发送成功 to{to_number} sid{sid}) return sid except TwilioRestException as e: logging.error(fTwilio错误 code{e.code} msg{e.msg}) raise except Exception as e: logging.error(f未知错误 {e}) raise把日志预留好后面排查问题时你会感谢自己。5. 进阶功能定时任务与动态消息5.1 用 APScheduler 做定时调度定时任务是短信通知系统最常见的需求。你可以选择系统 Cron也可以用 Python 里的 APScheduler 库统一管理。我推荐 APScheduler因为它的调度规则更灵活而且能直接集成到你的 Python 项目里不用依赖系统环境。安装pip install apscheduler一个每分钟执行一次的任务可以这么写from apscheduler.schedulers.blocking import BlockingScheduler scheduler BlockingScheduler() def job(): body 定时提醒该喝水了。 to_number os.environ[ALERT_TO_NUMBER] safe_send(to_number, body) # 在每天上午9点执行 scheduler.add_job(job, CronTrigger, hour9, minute0, idmorning_remind) scheduler.start()CronTrigger 支持非常丰富的规则hour9, minute30代表每天 9:30day_of_weekmon-fri代表周一到周五hour9-18, minute*/15代表 9 点到 18 点每 15 分钟一次。这些规则记不住没关系用的时候查文档就行。5.2 动态参数拼装消息固定内容只能算 hello world真正用得上的消息往往包含动态数据。比如每天的最高温度、股票收盘价、服务器负载。这些数据可以从 API、数据库或爬虫获取。我写了一个简单的数据来源模拟从本地 JSON 文件读取内容拼接到短信里。import json def load_payload(): with open(report.json, r, encodingutf-8) as f: data json.load(f) return data def build_message(data): return f【日报】今日完成 {data[completed_tasks]} 项任务新增 {data[new_tasks]} 项待办。 def job(): data load_payload() body build_message(data) to_number os.environ[ALERT_TO_NUMBER] safe_send(to_number, body)模板字符串用 f-string 或者 format 都行。需要注意短信有长度限制单条短信通常 160 个字符。超过 160 字符 Twilio 会自动拆成多条并按多条计费。我的建议是保持正文简短把重要的信息放前面这样即使被截断也能传达关键内容。5.3 避免重复触发导致重复发送定时任务最常见的操作失误是调度器在应用重启后重复执行积压的任务。APScheduler 默认行为是启动时不会执行之前错过的任务但它支持misfire_grace_time参数来控制容错窗口。如果你的任务本身应该保证不能被跳过比如每分钟读取一次传感器数据那不用太担心。但如果是每天一次的报表万一调度器因为网络问题停了 5 分钟你肯定希望它恢复后先补发上一次的。这时可以设置scheduler.add_job( job, CronTrigger, hour9, minute0, iddaily_report, misfire_grace_time3600, coalesceTrue )misfire_grace_time表示任务原定执行时间之后最多延迟多久仍然执行。coalesceTrue表示如果错过了多次调度只执行最后一次。这两个参数对于生产环境非常重要避免短信轰炸。6. 工程化改造配置管理与模块拆分项目一旦开始变大所有代码堆在一个文件里就会变成维护噩梦。我参照自己的其他项目经验把这个小系统拆成了三个模块。6.1 目录结构sms-notifier/ ├── venv/ # 虚拟环境 ├── config.py # 配置读取 ├── sms_sender.py # 发送逻辑 ├── scheduler_jobs.py # 定时任务 ├── data/ │ └── report.json # 动态数据源 ├── logs/ │ └── sms_notifier.log # 运行日志 └── requirements.txt # 依赖清单6.2 config.py 示例统一管理配置避免在业务代码里到处读取环境变量import os class Config: ACCOUNT_SID os.environ[TWILIO_ACCOUNT_SID] AUTH_TOKEN os.environ[TWILIO_AUTH_TOKEN] FROM_NUMBER os.environ[TWILIO_FROM_NUMBER] ALERT_TO_NUMBER os.environ[ALERT_TO_NUMBER] LOG_FILE os.path.join(os.path.dirname(__file__), logs, sms_notifier.log)6.3 sms_sender.py 示例把发送逻辑封装成类方便复用和测试import logging from twilio.rest import Client from twilio.base.exceptions import TwilioRestException from config import Config class SmsSender: def __init__(self): self.client Client(Config.ACCOUNT_SID, Config.AUTH_TOKEN) self.from_number Config.FROM_NUMBER logging.basicConfig( filenameConfig.LOG_FILE, levellogging.INFO, format%(asctime)s %(levelname)s %(message)s ) def send(self, to_number, body): try: message self.client.messages.create( toto_number, from_self.from_number, bodybody ) logging.info(fsend ok to{to_number} sid{message.sid}) return message.sid except TwilioRestException as e: logging.error(ftwilio error code{e.code} msg{e.msg}) raise7. 监控与自定义告警让系统更有实用价值定时提醒只是最基础的使用场景。一旦把这个系统理解成通知通道你会发现它能干的活非常多。我自己在项目中用得最顺手的是服务监控告警。7.1 健康检查与告警假设你有一个 Web 服务你希望它在宕机时及时发短信通知你。那你需要写一个探活函数定时检查服务的 HTTP 状态码。import requests from sms_sender import SmsSender import time sender SmsSender() def check_service_health(): url http://你的服务地址/health try: resp requests.get(url, timeout5) if resp.status_code 500: sender.send(Config.ALERT_TO_NUMBER, f服务异常HTTP {resp.status_code}) else: print(服务正常) except requests.RequestException: sender.send(Config.ALERT_TO_NUMBER, 服务无法访问请检查进程是否存活。)这里要注意一个细节检查频率不能太高否则故障恢复前会持续发送大量短信。我通常会加一个简单的状态标记只有状态改变时才发通知。7.2 持续性故障中的降噪机制降噪机制可以这样做记录上一次状态如果当前状态与上次相同并且上次已经发过通知就跳过发送。这样服务虽然持续异常但你只会在状态变化的那一刻收到一条短信。用一个模块级变量或小文件来存储状态即可last_status_file last_status.txt def read_last_status(): try: with open(last_status_file, r) as f: return f.read().strip() except FileNotFoundError: return unknown def write_last_status(status): with open(last_status_file, w) as f: f.write(status)这个小小的技巧能让你的短信条数和费用都大幅下降而且也不会因为短信轰炸让你把通知功能关掉。7.3 消息内容的最佳实践短信内容不是随便写写就发出去的。从实际使用效果看一条好的通知短信应该包含是谁、什么事件、严重级别、怎么处理四要素。比如下面这两条对比普通写法服务异常好一点的写法【监控告警】服务A在2025-01-20 14:33:22发生故障错误码500连续失败3次请立即处理。我发现很多初学者写通知短信时只写出错啦等真正收到短信完全想不起来是哪个服务、出了什么事。别偷懒把关键信息拼进去。8. 常见问题与排查技巧实录这个项目看着不起眼但实操中问题非常多。我基本都踩过整理出来给你参考。8.1 发送失败错误码 21408这个错误代表你的 Twilio 号码没有短信权限或者号码与短信功能不匹配。解决方法是去控制台重新选一个支持短信的号码并确认该号码已启用短信能力。8.2 收不到短信但接口返回成功遇到这种情况先别怀疑 API大概率是号码格式问题或者运营商延迟。先查消息状态在 Twilio 控制台或通过 API 查询 message.sid 的状态。如果状态是delivered说明运营商已送达如果状态是undelivered可能是目标手机拒收或内容被过滤。8.3 认证失败错误码 20003这个错误很直白就是 Auth Token 配错了或者 SID 填的别人的。检查环境变量是否正确还要注意不要有空格和换行符。我自己的环境变量文件偶尔会因为复制粘贴多了一个空格排查了半天才发现。8.4 时区问题定时任务默认使用服务器本地时区。如果你部署在云服务器上系统时区不一定是北京时间可能导致任务在错误的时间触发。在创建 CronTrigger 时指定时区from apscheduler.triggers.cron import CronTrigger from pytz import timezone trigger CronTrigger(hour9, minute0, timezonetimezone(Asia/Shanghai))8.5 内存泄漏和日志增长长时间运行的调度任务要注意日志文件增长。logging 默认会无限制追加时间长了磁盘会被打满。加一个简单的 RotatingFileHandlerfrom logging.handlers import RotatingFileHandler handler RotatingFileHandler(sms_notifier.log, maxBytes5*1024*1024, backupCount2)这样单个日志超过 5MB 会自动轮转。8.6 快速自查速查表现象可能原因排查位置收到错误 21408号码短信权限未开启控制台号码配置接口返回成功但没收到短信号码格式错误/状态为失败查询消息状态认证失败SID/Token 错误环境变量定时任务不触发时区/调度器未启动检查日志走时重复收到短信调度任务重复注册检查 add_job 调用次数9. 实战经验与心得9.1 从零搭建的最短路径如果你正准备照着做我给你一条最短路径注册 Twilio拿免费额度。购买或试用一个支持短信的号码。创建虚拟环境安装 twilio。跑通最小发送代码。加入定时任务。加入异常处理和日志。推送到 GitHub但务必使用.gitignore忽略虚拟目录和日志文件。9.2 一个小建议先用假的发送逻辑测试我在真正对接 Twilio 之前会先用一个假的发送函数来测试整个调度逻辑是否正确。这样既省短信费又避免把测试短信发到真实手机号上。# mock_sender.py def send(to_number, body): print(f[MOCK] 发送到 {to_number}: {body}) return mock-sid把sms_sender.py导入的地方替换成mock_sender.py等测完调度流程再换回真实 SDK。这个习惯帮我节省了很多多余的短信条数。9.3 关于成本控制Twilio 的计费是按条数和目的地费率来的。发到中国大陆的短信费率不算低所以控制成本的方法就是减少发送量。我已经在降噪机制上做了优化再一个就是不要用短信用来发营销内容它天生适合的是高频低延迟的通知。要发广告请去找营销短信供应商。9.4 这个系统还能怎么扩展我在原有代码基础上给项目加过几个扩展点很容易往里面塞功能Webhook 接口用 Flask 写一个 HTTP 接口接收 JSON 数据后触发短信发送这样其他系统可以调接口发短信。告警模板把内容模板放到单独文件里支持占位符替换。多收件人传一个号码列表循环发送注意每个收件人之间加错误隔离。状态回写通过 Twilio 回调接口更新数据库记录每条短信的最终状态。最终你得到的不仅是一个发短信小程序而是一个真正可复用的通知中心。我在实际使用中最满意的一点就是这套系统晚上静默运行第二天醒来手机里已经有需要的提醒。它不需要我盯着不会再因为忙忘事。踩过几次坑之后我现在更看重它的稳定性——不发错、不漏发、不重复发比任何花哨功能都重要。如果你也打算做类似的东西建议先把这一层打磨好。
