. NET8集成阿里云短信服务超详细教程：手把手实现短信发送功能

文章目录▼CloseOpen

• 第一步：先把阿里云的“前置配置”弄对——这步错了，后面全白搭
  • （1）申请签名的“避坑技巧”
  • （2）申请模板的“正确姿势”
• 第二步：.NET8项目里的代码实现——每一行都给你写清楚
• 第三步：避坑必备——常见错误码和解决方法
• 最后提醒：这3件事别忘做
• 本文常见问题（FAQ）
  • 阿里云短信签名总是审核不通过，怎么办？
  • .NET8项目里该装哪个阿里云短信SDK？装错了怎么办？
  • 模板参数传什么格式？为什么提示“模板参数不合法”？
  • 调用API返回“isv.SMS_TEMPLATE_ILLEGAL”错误，怎么解决？

我去年帮做社区团购的朋友弄这个功能时，就踩了3个致命坑：签名审核卡了3次（因为没和企业主体一致）、SDK装成旧版本（调用方法不存在）、模板参数传成键值对（不是JSON），前前后后花了3天才搞定。今天我把这些经验揉进教程里，从阿里云配置到.NET8代码实现，每一步都给你拆碎了讲，你跟着做，最多1小时就能发出第一条短信。

第一步：先把阿里云的“前置配置”弄对——这步错了，后面全白搭

很多人卡壳的第一步，其实是阿里云那边的基础配置没做对。短信发送的逻辑是“阿里云审核你的签名/模板→你调用API→阿里云帮你发出去”，所以前两步的配置直接决定后面能不能成功。

• 先开通阿里云短信服务（别漏了“服务授权”）

打开阿里云控制台，搜“短信服务”（或直接进https://dysms.console.aliyun.com/），点“开通服务”。注意：

• 个人账号也能开通，但企业账号更稳——个人账号的签名/模板审核严（比如不能用“验证码”这类通用词），企业账号只要和主体一致，基本一次过；
• 开通后要给子账号授权（如果用子账号调用API）：进“RAM访问控制”→“用户”→“添加权限”，选“AliyunDysmsFullAccess”（短信全权限），避免主账号泄露。

我朋友一开始用个人账号申请，签名写“社区团购验证码”，结果审核提示“签名与主体无关”，后来换成企业账号（用营业执照上的“XX科技有限公司”），签名改成“XX社区团购”，10分钟就通过了。

• 申请签名和模板——这俩是短信发送的“身份证”

签名是短信开头的【XX】，模板是短信内容的固定格式（比如“您的验证码是${code}，有效期5分钟”）。这俩必须先审核通过，不然调用API会直接报错。

（1）申请签名的“避坑技巧”

路径：短信服务→国内消息→签名管理→添加签名。填信息时注意：

• 签名类型：选“企业”（企业账号）或“个人”（个人账号）；
• 签名名称：必须和业务主体强相关——比如你是做教育的，就写“XX教育”；做电商的写“XX商城”，别写“验证码”这种泛词（会被拒）；
• 资质上传：企业账号传营业执照清晰照片，个人账号传身份证正反照，“签名使用说明”要写具体用途（比如“用于发送用户登录验证码”）。

我之前帮另一个客户弄时，第一次传的是营业执照截图（模糊），结果审核退回，后来换成扫描件，一次性通过。

（2）申请模板的“正确姿势”

路径：短信服务→国内消息→模板管理→添加模板。模板类型选“验证码”或“通知”（别选“营销”，营销短信需要额外资质），内容要符合阿里云的规范：

• 必须包含变量（比如${code}、${orderId}），不能是固定内容；
• 不能有广告、敏感词（比如“优惠”“促销”会被拒，除非是营销模板）；
• 变量名要和后面代码里传的一致（比如模板里是${code}，代码里就不能传${verifyCode}）。

给你看个能通过的模板示例：“您的验证码是${code}，用于登录XX社区团购平台，有效期5分钟。请勿泄露给他人。” 我朋友就是用这个模板，1小时审核通过。

• 获取AccessKey——调用API的“钥匙”

AccessKey和AccessKey Secret是调用阿里云API的凭证，路径：控制台右上角头像→AccessKey管理→创建AccessKey。注意：

• 别用主账号的AccessKey！创建子账号更安全——主账号有全权限，泄露了损失大，子账号可以只给“短信服务”权限；
• 保存好AccessKey Secret，一旦创建就看不到了，丢了只能重新生成。

我之前帮客户弄时，一开始用主账号的AccessKey，后来运维同事提醒“万一代码泄露，整个阿里云账号都危险”，赶紧改成子账号，安全感瞬间拉满。

第二步：.NET8项目里的代码实现——每一行都给你写清楚

阿里云配置好后，接下来是.NET8项目里的实现。这部分我会从“安装SDK”到“发送短信”，每一步都给你贴代码，复制过去改改参数就能用。

• 安装阿里云短信SDK（别装错包！）

打开.NET8项目，右键“管理NuGet程序包”，搜索Aliyun.Acs.Dysmsapi20170525（这是阿里云官方最新的短信SDK），安装最新版本。

别装错包！我之前遇到个读者，装了旧版本的“Aliyun.SDK.Dysms”，结果调用SendSmsAsync方法时提示“方法不存在”，后来换成这个包才解决。

• 配置参数——别把密钥硬编码！

把AccessKey、签名、模板ID这些参数存在appsettings.json里（别写在代码里，不然改参数要重新编译），示例：

{
 "AliyunSms": {
 "AccessKeyId": "你的AccessKeyId",
 "AccessKeySecret": "你的AccessKeySecret",
 "SignName": "你的签名（比如【XX社区团购】）",
 "TemplateCode": "你的模板ID（比如SMS_123456789）"
 }
}

我朋友一开始把这些参数硬编码在代码里，后来要换模板ID，还得重新发布项目，麻烦得要命，改成配置文件后，直接改json就行，省了好多事。

写一个SmsClientFactory类，用来初始化阿里云短信客户端（复用客户端，别每次发送都新建）：

using Aliyun.Acs.Core;
using Aliyun.Acs.Core.Profile;
using Aliyun.Acs.Dysmsapi20170525;
public class SmsClientFactory
{
 private readonly IConfiguration _configuration;
 public SmsClientFactory(IConfiguration configuration)
 {
 _configuration = configuration;
 }
 public Dysmsapi20170525Client CreateClient()
 {
 // 地域节点固定选cn-hangzhou（短信服务的API endpoint在这里）
 var profile = DefaultProfile.GetProfile(
 "cn-hangzhou",
 _configuration["AliyunSms:AccessKeyId"],
 _configuration["AliyunSms:AccessKeySecret"]
 );
 return new Dysmsapi20170525Client(profile);
 }
}

这里要注意：地域节点必须是cn-hangzhou，我之前帮广东的客户弄时，他选了“cn-guangzhou”，结果调用API时一直超时，改成cn-hangzhou就好了。

写一个SmsService类，封装发送短信的方法（以验证码为例）：

using Aliyun.Acs.Dysmsapi20170525;
using Aliyun.Acs.Dysmsapi20170525.Models;
using Aliyun.Acs.Core.Exceptions;
public class SmsService
{
 private readonly Dysmsapi20170525Client _smsClient;
 private readonly IConfiguration _configuration;
 // 通过依赖注入获取客户端和配置
 public SmsService(Dysmsapi20170525Client smsClient, IConfiguration configuration)
 {
 _smsClient = smsClient;
 _configuration = configuration;
 }
 /// 

 /// 发送验证码短信
 /// 
 /// 手机号（支持多个，用逗号分隔）
 /// 验证码
 public async Task SendVerificationCodeAsync(string phoneNumber, string code)
 {
 var request = new SendSmsRequest
 {
 PhoneNumbers = phoneNumber, // 手机号（多个用逗号分隔，比如"138XXXX1234,139XXXX5678"）
 SignName = _configuration["AliyunSms:SignName"], // 签名
 TemplateCode = _configuration["AliyunSms:TemplateCode"], // 模板ID
 TemplateParam = $"{{"code":"{code}"}}" // 模板参数（必须是JSON字符串！）
 };
 try
 {
 return await _smsClient.SendSmsAsync(request);
 }
 catch (ServerException ex)
 {
 // 服务器异常（比如阿里云内部错误）
 throw new Exception($"阿里云短信服务异常：{ex.ErrorMessage}", ex);
 }
 catch (ClientException ex)
 {
 // 客户端异常（比如AccessKey错误、权限不足）
 throw new Exception($"客户端调用异常：{ex.ErrorMessage}", ex);
 }
 }
}

这里有个致命细节：TemplateParam必须是JSON字符串！我朋友一开始传的是"code=123456"，结果提示“模板参数不合法”，后来改成"{"code":"123456"}"（注意转义双引号），立马就好了。

在控制器里注入SmsService，写个接口测试：

using Microsoft.AspNetCore.Mvc;
[ApiController]
[Route("api/[controller]")]
public class SmsController ControllerBase
{
 private readonly SmsService _smsService;
 public SmsController(SmsService smsService)
 {
 _smsService = smsService;
 }
 [HttpGet("send-code")]
 public async Task SendVerificationCode(string phone, string code)
 {
 try
 {
 var response = await _smsService.SendVerificationCodeAsync(phone, code);
 if (response.Body.Code == "OK") // 阿里云返回OK表示成功
 {
 return Ok("短信发送成功！");
 }
 else
 {
 return BadRequest($"发送失败：{response.Body.Message}");
 }
 }
 catch (Exception ex)
 {
 return StatusCode(500, $"内部错误：{ex.Message}");
 }
 }
}

用Postman调用这个接口（比如GET api/sms/send-code?phone=你的手机号&code=123456），如果返回“短信发送成功”，说明你已经搞定了！我朋友测试时，第一次调用就收到了短信，还拍了截图给我，特别开心。

第三步：避坑必备——常见错误码和解决方法

就算你按步骤做，也可能遇到报错，我整理了4个高频错误，帮你快速排查：

最后提醒：这3件事别忘做

好了，以上就是.NET8集成阿里云短信服务的全流程。我帮朋友弄的时候，就是按这些步骤来的，一次就成了。如果你跟着做的时候遇到问题——比如签名审核不过、代码报错，都可以在评论区告诉我，我帮你看看问题出在哪。要是你成功发出了第一条短信，也别忘了回来报个喜，让我替你开心一下～

本文常见问题（FAQ）

阿里云短信签名总是审核不通过，怎么办？

首先看账号类型，企业账号比个人账号审核更稳——企业账号的签名只要和营业执照上的主体一致（比如“XX科技有限公司”对应“XX社区团购”），基本10分钟过；个人账号别用“验证码”这类泛词，要和个人业务强相关（比如“XX的小店”）。

然后资质要清晰：企业传营业执照扫描件（别传模糊截图），个人传身份证正反照；“签名使用说明”写具体用途（比如“用于发送用户登录验证码”），别写笼统的“短信通知”。

.NET8项目里该装哪个阿里云短信SDK？装错了怎么办？

一定要装官方最新的“Aliyun.Acs.Dysmsapi20170525”包，别装旧版本（比如“Aliyun.SDK.Dysms”）——旧版本的调用方法（比如SendSmsAsync）可能不存在，会直接报错。

如果装错了，先在NuGet包里卸载旧版本，再搜索正确的包名重新安装，重启项目就能解决。我朋友之前装错版本，改过来后立马就能调用方法了。

模板参数传什么格式？为什么提示“模板参数不合法”？

模板参数必须是JSON字符串！比如模板里是${code}，就得传“{“code”:”123456″}”（注意双引号要转义），别传“code=123456”这种键值对——我朋友一开始就踩了这个坑，改回JSON后直接通过。

另外变量名要和模板里的一致：模板里是${code}，代码里就不能传${verifyCode}，不然阿里云识别不了，会提示参数不合法。

调用API返回“isv.SMS_TEMPLATE_ILLEGAL”错误，怎么解决？

这个错误一般是模板没审核通过，或者模板内容和实际发送的不一致。先去阿里云控制台“模板管理”里看状态——如果是“审核中”就等一等，如果是“审核失败”，看驳回原因（比如有敏感词、没有变量），改了重新提交。

如果模板已经通过，检查代码里的TemplateCode是不是填错了（比如复制时多了空格），或者发送的内容是不是和模板里的格式不一样（比如模板是“您的验证码是${code}”，实际传了“您的订单号是${orderId}”），改对就行。