接手过几个企业微信自建应用的项目每次新人对接时几乎都会卡在同一个地方管理后台保存“接收消息服务器”配置时提示URL验证失败或者明明验证过了消息却一直推送不进来。这个环节看着只是填几个参数背后实际上是一条完整的加解密链路。我这次用.NET把整条链路拆开来讲从域名验证的原理、AES加解密的细节到消息接收、业务分发、被动回复的时序问题一次性说清楚。适合正在做企业微信应用接入的.NET开发者也适合被回调验证折磨过的朋友对照排查。1. 搞清企业微信应用接入的完整链路后再动手1.1 创建自建应用需要准备的三件套在企业微信管理后台创建一个自建应用后你会拿到三个关键参数很多人一开始分不清它们各自的用途CorpId企业ID当前企业的唯一标识回调解密出来的明文字段尾部会携带它用来确认消息确实是发给本企业的。AgentId应用ID自建应用的唯一编号业务上用来区分消息来自哪个应用。Secret应用密钥调用企业微信服务端API获取access_token时使用注意它不参与消息回调的加解密。也就是说回调验证和消息解密只依赖Token和EncodingAESKeySecret是另一条线。我在项目中见过有人把Secret也填进加解密逻辑里结果越搞越乱。1.2 两种“域名验证”要分清楚标题里说的“域名验证”在企业微信里其实对应两种不同的操作接收消息服务器的回调URL验证这是配置“接收消息服务器”时触发的验证。企业微信向你的URL发起GET请求带msg_signature、timestamp、nonce、echostr四个参数你需要验证签名、解密echostr、再原样返回明文。本文重点讲的就是这个。网页应用的可信域名校验如果你的应用要使用OAuth网页授权或JS-SDK需要在应用详情里配置可信域名然后下载一个校验文件放到域名根目录保证通过https://yourdomain/文件名.txt能访问到。这属于域名归属验证和回调加解密没有关系。把这两件事分开后面看文档就不会绕晕。1.3 从保存配置到收到第一条消息的完整时序我先把整条链路在脑子里过一遍再往下看代码会清晰很多在管理后台配置接收消息服务器填上公网可访问的URL、自定义Token、后台生成的EncodingAESKey。点击保存企业微信立即向URL发起GET验证请求。你的服务校验签名、解密echostr把解密后的明文内容作为响应返回。验证通过配置保存成功。用户给应用发消息或触发事件企业微信向同一URL发起POST请求请求体是包含Encrypt节点的XML。你读取Encrypt内容验签、解密得到明文XML。处理业务需要回复时构造明文回复XML加密后包一层响应XML返回不需要回复时直接返回字符串success。看到没有GET和POST走的是同一个URL但一个是验证、一个是收消息。很多坑都出在把这两个入口混在一起处理。2. 回调URL验证GET请求先验签名再解密EchoStr2.1 验证请求的构造方式和安全设计企业微信发起的GET验证请求参数是这样的参数名含义msg_signature签名串基于token、timestamp、nonce、echostr计算timestamp时间戳秒级nonce随机串echostr加密的随机字符串需要解密后原样返回为什么企业微信要用“验签解密”两步来做验证我的理解是这样的单纯验证URL可达并没有意义它要确认三件事。第一你确实持有Token这样能算出正确的签名第二你确实持有EncodingAESKey因为echostr是加密的只有解密成功并返回正确明文才算真正掌控了这把钥匙第三URL背后确实是你的服务而不是随便一个能响应请求的静态页面。这里的签名参数名是msg_signature不是微信公众平台那套的signature容易踩坑的就是拿老代码直接改。2.2 签名校验的算法细节与代码签名规则并不复杂把token、timestamp、nonce、echostr四个字符串按字典序排序拼接成一个字符串做SHA1哈希结果转小写十六进制字符串与msg_signature比对。需要注意“字典序”三个字C#里用StringComparer.Ordinal来排序而不是默认的CurrentCulture以免某些环境下排序结果不一致。using System.Security.Cryptography; using System.Text; public static class WeComSign { public static string BuildSignature(string token, string timestamp, string nonce, string encrypt) { var array new[] { token, timestamp, nonce, encrypt }; Array.Sort(array, StringComparer.Ordinal); var raw string.Concat(array); var hash SHA1.HashData(Encoding.UTF8.GetBytes(raw)); return Convert.ToHexString(hash).ToLowerInvariant(); } public static bool VerifySignature(string msgSignature, string token, string timestamp, string nonce, string encrypt) { if (string.IsNullOrEmpty(msgSignature) || string.IsNullOrEmpty(encrypt)) { return false; } var signature BuildSignature(token, timestamp, nonce, encrypt); return string.Equals(signature, msgSignature, StringComparison.OrdinalIgnoreCase); } }SHA1.HashData是.NET 5及以上才有的静态方法如果你的项目还在.NET Framework那就手动创建SHA1.Create()再调用ComputeHash。Convert.ToHexString同理也可以换成BitConverter.ToString(hash).Replace(-, ).ToLower()。2.3 解密EchoStr的返回要求验签通过后需要解密echostr。注意解密结果的结构是16字节随机字符串 4字节消息长度(网络字节序) 真正的EchoStr明文 企业CorpId你要返回的是中间的“真正的EchoStr明文”不是把整个解密结果返回也不是把echostr做Base64解码就返回。我见过一个失败案例对方直接把Convert.FromBase64String(echostr)转字符串返回后台一直提示URL验证失败本质上就是没搞懂这层封装。下面是一个完整的GET验证处理代码直接放在ASP.NET Core控制器里即可[ApiController] [Route(wecom)] public class WeComCallbackController : ControllerBase { private readonly ILoggerWeComCallbackController _logger; // 配置项与管理后台保持一致 private const string Token your-token; private const string EncodingAesKey your-encoding-aes-key; private const string CorpId your-corp-id; public WeComCallbackController(ILoggerWeComCallbackController logger) { _logger logger; } [HttpGet(callback)] public IActionResult Verify( [FromQuery] string msg_signature, [FromQuery] string timestamp, [FromQuery] string nonce, [FromQuery] string echostr) { if (!WeComSign.VerifySignature(msg_signature, Token, timestamp, nonce, echostr)) { _logger.LogWarning(URL验证签名失败); return Content(signature fail, text/plain); } try { var (echo, corpId) WeComCrypto.Decrypt(echostr, EncodingAesKey); if (corpId ! CorpId) { _logger.LogWarning(URL验证时CorpId不匹配解密得到: {CorpId}, corpId); return Content(corpid fail, text/plain); } return Content(echo, text/plain); } catch (Exception ex) { _logger.LogError(ex, echostr解密失败); return Content(decrypt fail, text/plain); } } }有一点要特别提醒响应的实体就是纯文本不要加多余的空格、换行或JSON包装。Content(echo, text/plain)在ASP.NET Core里默认就是UTF-8无BOM输出符合要求。3. .NET下企业微信加解密模块的完整实现3.1 企业微信的密文包格式拆解解密方法写起来不复杂但前提是理解企业微信的封装格式。它的设计很像一个自定义信封原始明文 16字节随机字符串 4字节消息长度(大端序) 消息体 企业CorpId然后使用EncodingAESKey做AES-256-CBC加密具体参数是密钥EncodingAESKey按Base64解码后的32字节。IV取密钥的前16字节。模式与填充CBC模式 PKCS7填充。输出加密后的字节数组做Base64编码得到字符串。这里有几个为什么值得说一下。加入16字节随机串保证相同内容每次加密出来的密文不同防止重放和模式分析。加入4字节消息长度解密后能准确截取消息体。末尾拼CorpId相当于收件人校验防止别人的报文拿到你这里还能解出“看似合理”的内容。3.2 解密方法从Base64到明文XMLusing System.Security.Cryptography; using System.Text; public static class WeComCrypto { public static (string Msg, string CorpId) Decrypt(string encrypt, string encodingAesKey) { if (string.IsNullOrEmpty(encrypt)) { throw new ArgumentException(密文不能为空, nameof(encrypt)); } var key Convert.FromBase64String(encodingAesKey); if (key.Length ! 32) { throw new CryptographicException(EncodingAESKey解码后长度必须为32字节); } var iv new byte[16]; Array.Copy(key, 0, iv, 0, 16); using var aes Aes.Create(); aes.Key key; aes.IV iv; aes.Mode CipherMode.CBC; aes.Padding PaddingMode.PKCS7; byte[] plainBytes; using (var input new MemoryStream(Convert.FromBase64String(encrypt))) using (var decryptor aes.CreateDecryptor()) using (var cryptoStream new CryptoStream(input, decryptor, CryptoStreamMode.Read)) using (var output new MemoryStream()) { cryptoStream.CopyTo(output); plainBytes output.ToArray(); } // 前16字节是随机串这里不校验 var msgLen (plainBytes[16] 24) | (plainBytes[17] 16) | (plainBytes[18] 8) | plainBytes[19]; if (msgLen 0 || 20 msgLen plainBytes.Length) { throw new CryptographicException(消息长度字段非法); } var msg Encoding.UTF8.GetString(plainBytes, 20, msgLen); var corpId Encoding.UTF8.GetString(plainBytes, 20 msgLen, plainBytes.Length - 20 - msgLen); return (msg, corpId); } }长度字段我特意用手动移位的方式读取没有用BitConverter因为企业微信这里明确是网络字节序大端而BitConverter在常见平台上默认是小端直接转会出错。手动移位在任何平台都稳。解密之后一定要判断CorpId是否等于自己的企业ID。这个校验能挡住不少“密文能解开但内容不属于当前企业”的脏数据。3.3 加密方法构造被动回复密文被动回复的加密过程正好反过来构造好明文回复XML后按同样的格式拼接、AES加密、Base64输出。public static string Encrypt(string msg, string encodingAesKey, string corpId) { if (string.IsNullOrEmpty(msg)) { throw new ArgumentException(消息不能为空, nameof(msg)); } var key Convert.FromBase64String(encodingAesKey); if (key.Length ! 32) { throw new CryptographicException(EncodingAESKey解码后长度必须为32字节); } var iv new byte[16]; Array.Copy(key, 0, iv, 0, 16); var random RandomNumberGenerator.GetBytes(16); var msgBytes Encoding.UTF8.GetBytes(msg); var lenBytes new byte[4]; lenBytes[0] (byte)((msgBytes.Length 24) 0xFF); lenBytes[1] (byte)((msgBytes.Length 16) 0xFF); lenBytes[2] (byte)((msgBytes.Length 8) 0xFF); lenBytes[3] (byte)(msgBytes.Length 0xFF); var corpIdBytes Encoding.UTF8.GetBytes(corpId); var plainBytes new byte[16 4 msgBytes.Length corpIdBytes.Length]; Buffer.BlockCopy(random, 0, plainBytes, 0, 16); Buffer.BlockCopy(lenBytes, 0, plainBytes, 16, 4); Buffer.BlockCopy(msgBytes, 0, plainBytes, 20, msgBytes.Length); Buffer.BlockCopy(corpIdBytes, 0, plainBytes, 20 msgBytes.Length, corpIdBytes.Length); using var aes Aes.Create(); aes.Key key; aes.IV iv; aes.Mode CipherMode.CBC; aes.Padding PaddingMode.PKCS7; using var encryptor aes.CreateEncryptor(); var cipherBytes encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length); return Convert.ToBase64String(cipherBytes); }随机串用RandomNumberGenerator.GetBytes(16)生成这是加密安全的随机数来源不要用Guid或者Random凑数。Random这类伪随机源在加密场景里属于不安全用法。4. 消息处理链路验签、解包、识别、被动回复4.1 POST消息入口的验签与解包用户发消息或触发事件后企业微信会向同一个URL发起POST请求。请求体是一个XML核心内容在Encrypt节点里xml ToUserName![CDATA[corpid]]/ToUserName AgentID1000002/AgentID Encrypt![CDATA[密文BASE64]]/Encrypt /xmlURL上的参数依然有msg_signature、timestamp、nonce签名计算时参与的四个字符串是token、timestamp、nonce、XML里的Encrypt内容。我给出一个完整的处理入口[HttpPost(callback)] public async TaskIActionResult Receive( [FromQuery] string msg_signature, [FromQuery] string timestamp, [FromQuery] string nonce) { string body; using (var reader new StreamReader(Request.Body, Encoding.UTF8)) { body await reader.ReadToEndAsync(); } var doc XDocument.Parse(body); var encrypt doc.Root?.Element(Encrypt)?.Value; if (string.IsNullOrEmpty(encrypt) || !WeComSign.VerifySignature(msg_signature, Token, timestamp, nonce, encrypt)) { _logger.LogWarning(POST消息验签失败); return Content(signature fail, text/plain); } string plainXml; try { var (msg, corpId) WeComCrypto.Decrypt(encrypt, EncodingAesKey); if (corpId ! CorpId) { _logger.LogWarning(消息CorpId不匹配); return Content(corpid fail, text/plain); } plainXml msg; } catch (Exception ex) { _logger.LogError(ex, 消息解密失败); return Content(decrypt fail, text/plain); } _logger.LogInformation(收到明文消息: {PlainXml}, plainXml); var replyXml ProcessMessage(plainXml); if (string.IsNullOrEmpty(replyXml)) { return Content(success, text/plain); } var encryptedReply WeComCrypto.Encrypt(replyXml, EncodingAesKey, CorpId); var timeStamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); var nonceOut Guid.NewGuid().ToString(N); var responseXml BuildEncryptedResponse(encryptedReply, timeStamp, nonceOut); return Content(responseXml, text/xml); } private static string BuildEncryptedResponse(string encrypt, string timeStamp, string nonce) { var signature WeComSign.BuildSignature(Token, timeStamp, nonce, encrypt); return $xml Encrypt![CDATA[{encrypt}]]/Encrypt MsgSignature![CDATA[{signature}]]/MsgSignature TimeStamp{timeStamp}/TimeStamp Nonce![CDATA[{nonce}]]/Nonce /xml; }这个入口的ProcessMessage返回的是明文回复XML如果不回复则返回null。响应加密XML里的TimeStamp和Nonce可以自己生成但签名必须用同一组值来计算。4.2 明文XML的消息类型与分发策略解密后的明文XML结构是企业微信定义好的。下面是我在项目里见过的主要类型MsgType含义关键字段text文本消息Contentimage图片消息PicUrl, MediaIdvoice语音消息MediaId, Format, Recognitionvideo视频消息MediaId, ThumbMediaIdlocation位置消息Location_X, Location_Y, Scale, Labellink链接消息Title, Description, Urlevent事件消息Event, EventKey事件消息里比较常见的是subscribe用户关注、enter_agent用户进入应用、click点击应用菜单、location上报地理位置。事件消息一般不需要回复直接返回success即可。业务分发我建议用清晰的switch结构避免一堆if嵌套private string? ProcessMessage(string plainXml) { var root XDocument.Parse(plainXml).Root; var msgType root.Element(MsgType)?.Value; var fromUser root.Element(FromUserName)?.Value; var toUser root.Element(ToUserName)?.Value; switch (msgType) { case text: var content root.Element(Content)?.Value; _logger.LogInformation(收到文本消息: {Content}, content); return BuildTextReply(fromUser, toUser, $你发送的是{content}); case event: var eventName root.Element(Event)?.Value; var eventKey root.Element(EventKey)?.Value; _logger.LogInformation(收到事件: {Event}, Key: {EventKey}, eventName, eventKey); if (eventName enter_agent) { return BuildTextReply(fromUser, toUser, 欢迎进入应用); } return null; default: _logger.LogInformation(未处理的消息类型: {MsgType}, msgType); return null; } } private static string BuildTextReply(string fromUser, string toUser, string content) { var timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds(); return $xml ToUserName![CDATA[{fromUser}]]/ToUserName FromUserName![CDATA[{toUser}]]/FromUserName CreateTime{timestamp}/CreateTime MsgType![CDATA[text]]/MsgType Content![CDATA[{content}]]/Content /xml; }注意被动回复明文XML里的ToUserName要填发送者FromUserName要填企业的CorpId和接收时正好相反。很多人第一次写这里会把两个节点填反结果消息发不出去。4.3 被动回复的时序要求与success策略被动回复有一个硬性限制必须在5秒内响应。这里说的响应是指你的服务向企业微信服务器返回完整内容而不是业务处理完成。如果你的业务逻辑比较重比如要查数据库、调三方接口5秒经常不够。这时候有两个选择先返回success让企业微信认为处理结束然后自己另起一个后台任务继续处理处理完通过“发送应用消息”的API主动推给用户。想办法优化处理链路保证5秒内能构造出回复。我个人的经验是能用success就用success被动回复适合轻量场景。千万不要为了凑回复而阻塞请求线程一旦超时企业微信会重试多次最终可能导致同一条消息被重复处理。谈到重试就一定要提幂等。企业微信因超时或网络问题会对同一消息重试普通消息里有MsgId字段事件消息没有MsgId只能根据FromUserName加CreateTime加Event来拼一个业务幂等键。我在项目里用数据库唯一索引做去重入库前先查一次简单有效。**5. 接入过程中我踩过的坑和调试建议5.1 回调验证总是失败的三个真实原因我在实际项目里排查过三种典型的验证失败基本覆盖了90%的场景。第一种是返回内容错误。最常见的是把解密后的完整内容返回了或者返回的内容带了换行、空格、BOM。企业微信比对的是echostr解密后的字符串多一个字符都不行。第二种是签名参数名搞错。老项目从微信公众平台迁移过来时容易把msg_signature写成signature或者签名计算的四个元素里混入了AgentId。签名计算的输入必须是token、timestamp、nonce、echostr或Encrypt这四个一个都不能多。第三种是密钥不一致。管理后台点“随机生成”得到的EncodingAESKey和代码里配置的不一致或者复制时多了一个空格。Convert.FromBase64String在遇到非法字符时直接抛异常日志里会非常明显。还有一种相对隐蔽的情况服务部署在反向代理后面代理把query string丢弃了或者改了URL大小写。这种会让验签永远失败排查时除了看应用日志还要看网关日志。5.2 消息解密报Padding异常的排查如果你遇到CryptographicException: Padding is invalid and cannot be removed多半不是算法写错而是数据本身有问题。我按频率排了一下EncodingAESKey配置错了或者后台重置过密钥但代码没同步。密文在传输中被截断比如网关对body大小有限制把XML截断了一半。CorpId和加密时不一致。解密出来的CorpId如果乱码说明整个明文结构都被破坏自然也会报Padding异常。某些框架自动修改了请求体。我遇到过请求经过某个日志中间件后body流被读走但没有复位导致控制器读到空body解析不出Encrypt。排查这类问题第一步永远是打原始报文日志。把URL参数、请求体、解密用的CorpId、EncodingAESKey长度都打出来先确认数据完整再去怀疑算法。还有一个小细节Base64字符串里的在URL参数里会被解码成空格但在POST的XML body里不会。如果在GET验证时你在网关日志里看到密文里的变成了空格那只是日志显示问题ASP.NET Core的模型绑定会自动URL解码还原不需要手动处理。5.3 本地调试的实用手段本地调试企业微信回调最麻烦的是公网回调地址。我建议在项目早期就用内网穿透工具把本地服务临时暴露到公网或者直接部署到一台测试服务器验证整个链路后再迁回正式环境。内网穿透时要注意URL路径和正式环境保持一致避免传参差异。第二个建议是做一个原始报文记录开关。在回调入口把msg_signature、timestamp、nonce、body全文记录到日志或数据库排查问题时可以完整还原企业微信到底发了什么。这个开关在正式环境建议默认关闭需要排查时再打开避免日志量过大。第三个建议是先把加解密模块单独验证再接入业务逻辑。用企业微信后台或文档里提供的示例数据跑一遍Encrypt和Decrypt确保和你对应用例的结果一致。这里建议多做几组不同长度、包含中文和特殊字符的样本比如中文、XML转义字符、Emoji都能正常往返才算稳。还有一点务必注意Token和EncodingAESKey属于敏感配置不要写死在代码里用环境变量或配置中心管理日志里也要做脱敏。我在一个项目里见过有人为了方便把EncodingAESKey直接打在启动日志里后来整个密钥被迫重置这个教训挺深刻的。 
长河君 · 2026/10/20 20:21:02 · 阅读 1.2k 企业微信回调验证与AES加解密：.NET开发者接入指南
接手过几个企业微信自建应用的项目每次新人对接时几乎都会卡在同一个地方管理后台保存“接收消息服务器”配置时提示URL验证失败或者明明验证过了消息却一直推送不进来。这个环节看着只是填几个参数背后实际上是一条完整的加解密链路。我这次用.NET把整条链路拆开来讲从域名验证的原理、AES加解密的细节到消息接收、业务分发、被动回复的时序问题一次性说清楚。适合正在做企业微信应用接入的.NET开发者也适合被回调验证折磨过的朋友对照排查。1. 搞清企业微信应用接入的完整链路后再动手1.1 创建自建应用需要准备的三件套在企业微信管理后台创建一个自建应用后你会拿到三个关键参数很多人一开始分不清它们各自的用途CorpId企业ID当前企业的唯一标识回调解密出来的明文字段尾部会携带它用来确认消息确实是发给本企业的。AgentId应用ID自建应用的唯一编号业务上用来区分消息来自哪个应用。Secret应用密钥调用企业微信服务端API获取access_token时使用注意它不参与消息回调的加解密。也就是说回调验证和消息解密只依赖Token和EncodingAESKeySecret是另一条线。我在项目中见过有人把Secret也填进加解密逻辑里结果越搞越乱。1.2 两种“域名验证”要分清楚标题里说的“域名验证”在企业微信里其实对应两种不同的操作接收消息服务器的回调URL验证这是配置“接收消息服务器”时触发的验证。企业微信向你的URL发起GET请求带msg_signature、timestamp、nonce、echostr四个参数你需要验证签名、解密echostr、再原样返回明文。本文重点讲的就是这个。网页应用的可信域名校验如果你的应用要使用OAuth网页授权或JS-SDK需要在应用详情里配置可信域名然后下载一个校验文件放到域名根目录保证通过https://yourdomain/文件名.txt能访问到。这属于域名归属验证和回调加解密没有关系。把这两件事分开后面看文档就不会绕晕。1.3 从保存配置到收到第一条消息的完整时序我先把整条链路在脑子里过一遍再往下看代码会清晰很多在管理后台配置接收消息服务器填上公网可访问的URL、自定义Token、后台生成的EncodingAESKey。点击保存企业微信立即向URL发起GET验证请求。你的服务校验签名、解密echostr把解密后的明文内容作为响应返回。验证通过配置保存成功。用户给应用发消息或触发事件企业微信向同一URL发起POST请求请求体是包含Encrypt节点的XML。你读取Encrypt内容验签、解密得到明文XML。处理业务需要回复时构造明文回复XML加密后包一层响应XML返回不需要回复时直接返回字符串success。看到没有GET和POST走的是同一个URL但一个是验证、一个是收消息。很多坑都出在把这两个入口混在一起处理。2. 回调URL验证GET请求先验签名再解密EchoStr2.1 验证请求的构造方式和安全设计企业微信发起的GET验证请求参数是这样的参数名含义msg_signature签名串基于token、timestamp、nonce、echostr计算timestamp时间戳秒级nonce随机串echostr加密的随机字符串需要解密后原样返回为什么企业微信要用“验签解密”两步来做验证我的理解是这样的单纯验证URL可达并没有意义它要确认三件事。第一你确实持有Token这样能算出正确的签名第二你确实持有EncodingAESKey因为echostr是加密的只有解密成功并返回正确明文才算真正掌控了这把钥匙第三URL背后确实是你的服务而不是随便一个能响应请求的静态页面。这里的签名参数名是msg_signature不是微信公众平台那套的signature容易踩坑的就是拿老代码直接改。2.2 签名校验的算法细节与代码签名规则并不复杂把token、timestamp、nonce、echostr四个字符串按字典序排序拼接成一个字符串做SHA1哈希结果转小写十六进制字符串与msg_signature比对。需要注意“字典序”三个字C#里用StringComparer.Ordinal来排序而不是默认的CurrentCulture以免某些环境下排序结果不一致。using System.Security.Cryptography; using System.Text; public static class WeComSign { public static string BuildSignature(string token, string timestamp, string nonce, string encrypt) { var array new[] { token, timestamp, nonce, encrypt }; Array.Sort(array, StringComparer.Ordinal); var raw string.Concat(array); var hash SHA1.HashData(Encoding.UTF8.GetBytes(raw)); return Convert.ToHexString(hash).ToLowerInvariant(); } public static bool VerifySignature(string msgSignature, string token, string timestamp, string nonce, string encrypt) { if (string.IsNullOrEmpty(msgSignature) || string.IsNullOrEmpty(encrypt)) { return false; } var signature BuildSignature(token, timestamp, nonce, encrypt); return string.Equals(signature, msgSignature, StringComparison.OrdinalIgnoreCase); } }SHA1.HashData是.NET 5及以上才有的静态方法如果你的项目还在.NET Framework那就手动创建SHA1.Create()再调用ComputeHash。Convert.ToHexString同理也可以换成BitConverter.ToString(hash).Replace(-, ).ToLower()。2.3 解密EchoStr的返回要求验签通过后需要解密echostr。注意解密结果的结构是16字节随机字符串 4字节消息长度(网络字节序) 真正的EchoStr明文 企业CorpId你要返回的是中间的“真正的EchoStr明文”不是把整个解密结果返回也不是把echostr做Base64解码就返回。我见过一个失败案例对方直接把Convert.FromBase64String(echostr)转字符串返回后台一直提示URL验证失败本质上就是没搞懂这层封装。下面是一个完整的GET验证处理代码直接放在ASP.NET Core控制器里即可[ApiController] [Route(wecom)] public class WeComCallbackController : ControllerBase { private readonly ILoggerWeComCallbackController _logger; // 配置项与管理后台保持一致 private const string Token your-token; private const string EncodingAesKey your-encoding-aes-key; private const string CorpId your-corp-id; public WeComCallbackController(ILoggerWeComCallbackController logger) { _logger logger; } [HttpGet(callback)] public IActionResult Verify( [FromQuery] string msg_signature, [FromQuery] string timestamp, [FromQuery] string nonce, [FromQuery] string echostr) { if (!WeComSign.VerifySignature(msg_signature, Token, timestamp, nonce, echostr)) { _logger.LogWarning(URL验证签名失败); return Content(signature fail, text/plain); } try { var (echo, corpId) WeComCrypto.Decrypt(echostr, EncodingAesKey); if (corpId ! CorpId) { _logger.LogWarning(URL验证时CorpId不匹配解密得到: {CorpId}, corpId); return Content(corpid fail, text/plain); } return Content(echo, text/plain); } catch (Exception ex) { _logger.LogError(ex, echostr解密失败); return Content(decrypt fail, text/plain); } } }有一点要特别提醒响应的实体就是纯文本不要加多余的空格、换行或JSON包装。Content(echo, text/plain)在ASP.NET Core里默认就是UTF-8无BOM输出符合要求。3. .NET下企业微信加解密模块的完整实现3.1 企业微信的密文包格式拆解解密方法写起来不复杂但前提是理解企业微信的封装格式。它的设计很像一个自定义信封原始明文 16字节随机字符串 4字节消息长度(大端序) 消息体 企业CorpId然后使用EncodingAESKey做AES-256-CBC加密具体参数是密钥EncodingAESKey按Base64解码后的32字节。IV取密钥的前16字节。模式与填充CBC模式 PKCS7填充。输出加密后的字节数组做Base64编码得到字符串。这里有几个为什么值得说一下。加入16字节随机串保证相同内容每次加密出来的密文不同防止重放和模式分析。加入4字节消息长度解密后能准确截取消息体。末尾拼CorpId相当于收件人校验防止别人的报文拿到你这里还能解出“看似合理”的内容。3.2 解密方法从Base64到明文XMLusing System.Security.Cryptography; using System.Text; public static class WeComCrypto { public static (string Msg, string CorpId) Decrypt(string encrypt, string encodingAesKey) { if (string.IsNullOrEmpty(encrypt)) { throw new ArgumentException(密文不能为空, nameof(encrypt)); } var key Convert.FromBase64String(encodingAesKey); if (key.Length ! 32) { throw new CryptographicException(EncodingAESKey解码后长度必须为32字节); } var iv new byte[16]; Array.Copy(key, 0, iv, 0, 16); using var aes Aes.Create(); aes.Key key; aes.IV iv; aes.Mode CipherMode.CBC; aes.Padding PaddingMode.PKCS7; byte[] plainBytes; using (var input new MemoryStream(Convert.FromBase64String(encrypt))) using (var decryptor aes.CreateDecryptor()) using (var cryptoStream new CryptoStream(input, decryptor, CryptoStreamMode.Read)) using (var output new MemoryStream()) { cryptoStream.CopyTo(output); plainBytes output.ToArray(); } // 前16字节是随机串这里不校验 var msgLen (plainBytes[16] 24) | (plainBytes[17] 16) | (plainBytes[18] 8) | plainBytes[19]; if (msgLen 0 || 20 msgLen plainBytes.Length) { throw new CryptographicException(消息长度字段非法); } var msg Encoding.UTF8.GetString(plainBytes, 20, msgLen); var corpId Encoding.UTF8.GetString(plainBytes, 20 msgLen, plainBytes.Length - 20 - msgLen); return (msg, corpId); } }长度字段我特意用手动移位的方式读取没有用BitConverter因为企业微信这里明确是网络字节序大端而BitConverter在常见平台上默认是小端直接转会出错。手动移位在任何平台都稳。解密之后一定要判断CorpId是否等于自己的企业ID。这个校验能挡住不少“密文能解开但内容不属于当前企业”的脏数据。3.3 加密方法构造被动回复密文被动回复的加密过程正好反过来构造好明文回复XML后按同样的格式拼接、AES加密、Base64输出。public static string Encrypt(string msg, string encodingAesKey, string corpId) { if (string.IsNullOrEmpty(msg)) { throw new ArgumentException(消息不能为空, nameof(msg)); } var key Convert.FromBase64String(encodingAesKey); if (key.Length ! 32) { throw new CryptographicException(EncodingAESKey解码后长度必须为32字节); } var iv new byte[16]; Array.Copy(key, 0, iv, 0, 16); var random RandomNumberGenerator.GetBytes(16); var msgBytes Encoding.UTF8.GetBytes(msg); var lenBytes new byte[4]; lenBytes[0] (byte)((msgBytes.Length 24) 0xFF); lenBytes[1] (byte)((msgBytes.Length 16) 0xFF); lenBytes[2] (byte)((msgBytes.Length 8) 0xFF); lenBytes[3] (byte)(msgBytes.Length 0xFF); var corpIdBytes Encoding.UTF8.GetBytes(corpId); var plainBytes new byte[16 4 msgBytes.Length corpIdBytes.Length]; Buffer.BlockCopy(random, 0, plainBytes, 0, 16); Buffer.BlockCopy(lenBytes, 0, plainBytes, 16, 4); Buffer.BlockCopy(msgBytes, 0, plainBytes, 20, msgBytes.Length); Buffer.BlockCopy(corpIdBytes, 0, plainBytes, 20 msgBytes.Length, corpIdBytes.Length); using var aes Aes.Create(); aes.Key key; aes.IV iv; aes.Mode CipherMode.CBC; aes.Padding PaddingMode.PKCS7; using var encryptor aes.CreateEncryptor(); var cipherBytes encryptor.TransformFinalBlock(plainBytes, 0, plainBytes.Length); return Convert.ToBase64String(cipherBytes); }随机串用RandomNumberGenerator.GetBytes(16)生成这是加密安全的随机数来源不要用Guid或者Random凑数。Random这类伪随机源在加密场景里属于不安全用法。4. 消息处理链路验签、解包、识别、被动回复4.1 POST消息入口的验签与解包用户发消息或触发事件后企业微信会向同一个URL发起POST请求。请求体是一个XML核心内容在Encrypt节点里xml ToUserName![CDATA[corpid]]/ToUserName AgentID1000002/AgentID Encrypt![CDATA[密文BASE64]]/Encrypt /xmlURL上的参数依然有msg_signature、timestamp、nonce签名计算时参与的四个字符串是token、timestamp、nonce、XML里的Encrypt内容。我给出一个完整的处理入口[HttpPost(callback)] public async TaskIActionResult Receive( [FromQuery] string msg_signature, [FromQuery] string timestamp, [FromQuery] string nonce) { string body; using (var reader new StreamReader(Request.Body, Encoding.UTF8)) { body await reader.ReadToEndAsync(); } var doc XDocument.Parse(body); var encrypt doc.Root?.Element(Encrypt)?.Value; if (string.IsNullOrEmpty(encrypt) || !WeComSign.VerifySignature(msg_signature, Token, timestamp, nonce, encrypt)) { _logger.LogWarning(POST消息验签失败); return Content(signature fail, text/plain); } string plainXml; try { var (msg, corpId) WeComCrypto.Decrypt(encrypt, EncodingAesKey); if (corpId ! CorpId) { _logger.LogWarning(消息CorpId不匹配); return Content(corpid fail, text/plain); } plainXml msg; } catch (Exception ex) { _logger.LogError(ex, 消息解密失败); return Content(decrypt fail, text/plain); } _logger.LogInformation(收到明文消息: {PlainXml}, plainXml); var replyXml ProcessMessage(plainXml); if (string.IsNullOrEmpty(replyXml)) { return Content(success, text/plain); } var encryptedReply WeComCrypto.Encrypt(replyXml, EncodingAesKey, CorpId); var timeStamp DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString(); var nonceOut Guid.NewGuid().ToString(N); var responseXml BuildEncryptedResponse(encryptedReply, timeStamp, nonceOut); return Content(responseXml, text/xml); } private static string BuildEncryptedResponse(string encrypt, string timeStamp, string nonce) { var signature WeComSign.BuildSignature(Token, timeStamp, nonce, encrypt); return $xml Encrypt![CDATA[{encrypt}]]/Encrypt MsgSignature![CDATA[{signature}]]/MsgSignature TimeStamp{timeStamp}/TimeStamp Nonce![CDATA[{nonce}]]/Nonce /xml; }这个入口的ProcessMessage返回的是明文回复XML如果不回复则返回null。响应加密XML里的TimeStamp和Nonce可以自己生成但签名必须用同一组值来计算。4.2 明文XML的消息类型与分发策略解密后的明文XML结构是企业微信定义好的。下面是我在项目里见过的主要类型MsgType含义关键字段text文本消息Contentimage图片消息PicUrl, MediaIdvoice语音消息MediaId, Format, Recognitionvideo视频消息MediaId, ThumbMediaIdlocation位置消息Location_X, Location_Y, Scale, Labellink链接消息Title, Description, Urlevent事件消息Event, EventKey事件消息里比较常见的是subscribe用户关注、enter_agent用户进入应用、click点击应用菜单、location上报地理位置。事件消息一般不需要回复直接返回success即可。业务分发我建议用清晰的switch结构避免一堆if嵌套private string? ProcessMessage(string plainXml) { var root XDocument.Parse(plainXml).Root; var msgType root.Element(MsgType)?.Value; var fromUser root.Element(FromUserName)?.Value; var toUser root.Element(ToUserName)?.Value; switch (msgType) { case text: var content root.Element(Content)?.Value; _logger.LogInformation(收到文本消息: {Content}, content); return BuildTextReply(fromUser, toUser, $你发送的是{content}); case event: var eventName root.Element(Event)?.Value; var eventKey root.Element(EventKey)?.Value; _logger.LogInformation(收到事件: {Event}, Key: {EventKey}, eventName, eventKey); if (eventName enter_agent) { return BuildTextReply(fromUser, toUser, 欢迎进入应用); } return null; default: _logger.LogInformation(未处理的消息类型: {MsgType}, msgType); return null; } } private static string BuildTextReply(string fromUser, string toUser, string content) { var timestamp DateTimeOffset.UtcNow.ToUnixTimeSeconds(); return $xml ToUserName![CDATA[{fromUser}]]/ToUserName FromUserName![CDATA[{toUser}]]/FromUserName CreateTime{timestamp}/CreateTime MsgType![CDATA[text]]/MsgType Content![CDATA[{content}]]/Content /xml; }注意被动回复明文XML里的ToUserName要填发送者FromUserName要填企业的CorpId和接收时正好相反。很多人第一次写这里会把两个节点填反结果消息发不出去。4.3 被动回复的时序要求与success策略被动回复有一个硬性限制必须在5秒内响应。这里说的响应是指你的服务向企业微信服务器返回完整内容而不是业务处理完成。如果你的业务逻辑比较重比如要查数据库、调三方接口5秒经常不够。这时候有两个选择先返回success让企业微信认为处理结束然后自己另起一个后台任务继续处理处理完通过“发送应用消息”的API主动推给用户。想办法优化处理链路保证5秒内能构造出回复。我个人的经验是能用success就用success被动回复适合轻量场景。千万不要为了凑回复而阻塞请求线程一旦超时企业微信会重试多次最终可能导致同一条消息被重复处理。谈到重试就一定要提幂等。企业微信因超时或网络问题会对同一消息重试普通消息里有MsgId字段事件消息没有MsgId只能根据FromUserName加CreateTime加Event来拼一个业务幂等键。我在项目里用数据库唯一索引做去重入库前先查一次简单有效。**5. 接入过程中我踩过的坑和调试建议5.1 回调验证总是失败的三个真实原因我在实际项目里排查过三种典型的验证失败基本覆盖了90%的场景。第一种是返回内容错误。最常见的是把解密后的完整内容返回了或者返回的内容带了换行、空格、BOM。企业微信比对的是echostr解密后的字符串多一个字符都不行。第二种是签名参数名搞错。老项目从微信公众平台迁移过来时容易把msg_signature写成signature或者签名计算的四个元素里混入了AgentId。签名计算的输入必须是token、timestamp、nonce、echostr或Encrypt这四个一个都不能多。第三种是密钥不一致。管理后台点“随机生成”得到的EncodingAESKey和代码里配置的不一致或者复制时多了一个空格。Convert.FromBase64String在遇到非法字符时直接抛异常日志里会非常明显。还有一种相对隐蔽的情况服务部署在反向代理后面代理把query string丢弃了或者改了URL大小写。这种会让验签永远失败排查时除了看应用日志还要看网关日志。5.2 消息解密报Padding异常的排查如果你遇到CryptographicException: Padding is invalid and cannot be removed多半不是算法写错而是数据本身有问题。我按频率排了一下EncodingAESKey配置错了或者后台重置过密钥但代码没同步。密文在传输中被截断比如网关对body大小有限制把XML截断了一半。CorpId和加密时不一致。解密出来的CorpId如果乱码说明整个明文结构都被破坏自然也会报Padding异常。某些框架自动修改了请求体。我遇到过请求经过某个日志中间件后body流被读走但没有复位导致控制器读到空body解析不出Encrypt。排查这类问题第一步永远是打原始报文日志。把URL参数、请求体、解密用的CorpId、EncodingAESKey长度都打出来先确认数据完整再去怀疑算法。还有一个小细节Base64字符串里的在URL参数里会被解码成空格但在POST的XML body里不会。如果在GET验证时你在网关日志里看到密文里的变成了空格那只是日志显示问题ASP.NET Core的模型绑定会自动URL解码还原不需要手动处理。5.3 本地调试的实用手段本地调试企业微信回调最麻烦的是公网回调地址。我建议在项目早期就用内网穿透工具把本地服务临时暴露到公网或者直接部署到一台测试服务器验证整个链路后再迁回正式环境。内网穿透时要注意URL路径和正式环境保持一致避免传参差异。第二个建议是做一个原始报文记录开关。在回调入口把msg_signature、timestamp、nonce、body全文记录到日志或数据库排查问题时可以完整还原企业微信到底发了什么。这个开关在正式环境建议默认关闭需要排查时再打开避免日志量过大。第三个建议是先把加解密模块单独验证再接入业务逻辑。用企业微信后台或文档里提供的示例数据跑一遍Encrypt和Decrypt确保和你对应用例的结果一致。这里建议多做几组不同长度、包含中文和特殊字符的样本比如中文、XML转义字符、Emoji都能正常往返才算稳。还有一点务必注意Token和EncodingAESKey属于敏感配置不要写死在代码里用环境变量或配置中心管理日志里也要做脱敏。我在一个项目里见过有人为了方便把EncodingAESKey直接打在启动日志里后来整个密钥被迫重置这个教训挺深刻的。