小程序消息推送是运营者与用户互动的重要通道，一旦收不到消息，可能导致用户流失或业务中断。本教程将从后台配置、服务器环境、客户端权限三个层面，手把手教你排查并解决消息推送失败问题。无论你是技术小白还是运营人员，按照以下步骤操作，都能定位问题根源。
**前置准备**
1. **微信小程序后台账号**：具备管理员或开发者权限，用于查看订阅消息、模板消息、客服消息等配置。
2. **服务器或云开发环境**：如果小程序使用了自建服务器或云函数，需要能登录服务器查看日志或调试代码。
3. **测试手机**：准备两台不同品牌或系统的手机（如iOS和Android），用于模拟用户接收消息的场景。
4. **消息接收凭证**：提前记录下小程序的AppID、AppSecret，以及服务器配置中的Token、EncodingAESKey（如果使用加密模式）。
5. **代码编辑器**：用于修改服务器端代码或云函数，推荐VSCode或微信开发者工具。
---
**分步操作步骤**
**第一步：检查小程序后台消息配置**
1. 登录[微信公众平台](https://mp.weixin.qq.com/)，进入你的小程序管理后台。
2. 在左侧菜单栏找到“功能”板块，点击“订阅消息”或“模板消息”（根据你的消息类型选择）。确认你使用的模板ID或订阅消息模板是“已启用”状态，且参数设置正确。如果模板被禁用或删除，重新申请并提交审核。
3. 点击左侧“开发” -> “开发设置”，查看“服务器域名”配置。确保`request`、`socket`、`uploadFile`、`downloadFile`的合法域名都填写正确，且包含你的服务器地址。如果使用了WebSocket推送，必须配置`socket`域名。
4. 回到“开发” -> “开发管理”，点击“消息推送”旁的“启用”按钮。如果已启用，点击“修改配置”重新验证URL。在“URL”输入框里填写你的服务器接收地址（例如`https://yourdomain.com/wechat`），Token填写自定义字符串（例如`myToken123`），EncodingAESKey可以选择安全模式或兼容模式，点击“提交”按钮。如果提交后提示“Token验证失败”，说明服务器端代码未正确处理验证请求，请跳到第二步检查服务器代码。
5. 确认“消息推送”状态为“已启用”，且“消息加解密方式”与你的服务器代码一致。如果服务器使用明文模式，后台必须选择“明文模式”；如果使用安全模式，后台必须选择“安全模式”。
**第二步：验证服务器端接收消息能力**
1. 登录你的服务器，找到处理微信消息的入口文件（例如`index.php`、`app.js`或`server.py`）。打开该文件，确认代码中包含微信服务器验证逻辑。以Node.js为例，核心代码应包含：
```javascript
const crypto = require('crypto');
const token = 'myToken123'; // 必须与后台配置的Token一致
app.get('/wechat', (req, res) => {
const { signature, timestamp, nonce, echostr } = req.query;
const arr = [token, timestamp, nonce].sort();
const str = arr.join('');
const sha1 = crypto.createHash('sha1').update(str).digest('hex');
if (sha1 === signature) {
res.send(echostr); // 返回echostr给微信服务器
} else {
res.send('error');
}
});
```
2. 如果代码无误，但后台仍提示验证失败，检查服务器防火墙是否开放了80或443端口，以及域名是否正确解析到服务器IP。可以使用在线工具（如`ping`或`telnet`）测试域名连通性。
3. 验证通过后，模拟发送一条测试消息。在微信开发者工具中，选择“真机调试”，用测试手机扫描二维码。在手机上触发一个需要推送消息的操作（例如提交表单后发送模板消息）。然后立即查看服务器日志。以Node.js为例，在终端执行`tail -f /var/log/nginx/access.log`，观察是否有来自微信服务器IP的POST请求。如果没有任何请求，说明微信服务器未能成功连接你的服务器，检查域名证书是否有效，或是否使用了微信不支持的端口（只支持80和443）。
4. 如果收到POST请求，但返回状态码不是200，检查代码中是否有未捕获的错误。在服务器代码中增加日志输出，打印接收到的XML数据。例如在Node.js中：
```javascript
app.post('/wechat', (req, res) => {
let xml = '';
req.on('data', chunk => xml += chunk);
req.on('end', () => {
console.log('收到微信消息:', xml);
// 解析XML并返回成功
res.send('success');
});
});
```
如果日志显示`
**第三步：检查用户订阅与授权状态**
1. 打开微信开发者工具，在“调试器” -> “Console”中执行以下代码，查看当前用户是否已订阅消息：
```javascript
wx.getSetting({
withSubscriptions: true,
success(res) {
console.log(res.subscriptionsSetting);
}
});
```
如果`res.subscriptionsSetting`返回空对象或`itemSettings`为空，说明用户从未订阅过该模板。需要重新调用`wx.requestSubscribeMessage`弹出订阅授权框。
2. 检查订阅消息的模板ID是否与后台配置的完全一致。注意：模板ID是区分大小写的，且不同小程序之间不能混用。在后台复制模板ID，粘贴到前端代码中，确认没有多余空格或特殊字符。
3. 如果用户已经订阅，但消息仍收不到，检查订阅时设置的`tmplIds`参数是否包含了正确的模板ID。同时确认订阅行为是由用户主动触发（例如点击按钮），而不是在`onLoad`或`onShow`中自动调用。微信要求订阅操作必须由用户点击产生。
4. 对于一次性订阅消息，用户订阅后只能收到一次消息。如果用户再次触发相同模板，需要重新订阅。检查业务逻辑中是否在每次推送前都调用了订阅接口，或者使用了长期订阅（仅限特定行业）。
**第四步：排查客户端接收权限**
1. 在测试手机上打开微信，进入“我” -> “设置” -> “个人信息与权限” -> “系统权限管理”，找到你的小程序。确保“接收消息通知”开关是开启状态。如果关闭，手动打开。
2. 检查手机系统设置：在iOS中，进入“设置” -> “通知” -> “微信”，确保“允许通知”开关打开，且“声音”和“标记”至少开启一项。在Android中，进入“设置” -> “应用管理” -> “微信” -> “通知管理”，确保“允许通知”和“消息提醒”开启。不同品牌手机路径可能略有差异，但核心是确保微信的通知权限没有被系统拦截。
3. 如果手机开启了“免打扰”模式或“专注模式”，微信消息可能被静默。关闭这些模式后重试。
4. 在微信中，进入“我” -> “设置” -> “通用” -> “存储空间”，清理缓存后重启微信。有时候缓存异常会导致消息推送延迟或丢失。
**第五步：测试消息推送链路**
1. 使用微信官方提供的“小程序消息推送测试工具”。在微信公众平台后台，点击“工具” -> “小程序消息推送测试”，输入用户的OpenID（可以在小程序后台“用户管理”中找到），选择消息模板，填写参数后点击“发送”。如果工具提示“发送成功”，但用户手机收不到，问题出在用户端权限或微信服务器到用户端的链路。
2. 如果工具提示“发送失败”，查看失败原因。常见错误码包括：
- `40003`：OpenID无效，检查是否从错误接口获取了OpenID。
- `40037`：模板ID无效，重新从后台复制模板ID。
- `43101`：用户未订阅该模板，需要重新引导用户订阅。
- `45009`：接口调用频率超限，每个模板每天最多发送10万条（具体额度以小程序类型为准）。
3. 如果工具发送成功，但用户手机收不到，尝试更换网络环境（从WiFi切换到4G/5G）。有时候企业WiFi会拦截微信通知端口。
4. 在另一台手机上登录同一个微信账号，检查是否能收到消息。如果可以，说明原手机系统或微信版本有问题，尝试更新微信或重装。
**常见问题**
**Q：消息推送后用户手机完全没反应，但服务器日志显示发送成功。**
A：检查用户微信是否开启了“接收消息通知”和系统通知权限。另外，如果消息类型是“订阅消息”，用户只在微信“服务通知”中看到，不会弹出横幅提醒。引导用户进入微信“服务通知”查看。
**Q：后台配置消息推送时，一直提示“Token验证失败”。**
A：最常见原因是服务器代码中Token与后台配置不一致。检查Token是否包含空格或特殊字符，且两端完全一致。其次，确认服务器URL能通过公网访问，且返回的`echostr`没有被任何中间件修改（如Nginx的gzip压缩）。
**Q：用户订阅了消息，但推送时提示“43101”。**
A：用户订阅后，如果超过30天未使用，订阅状态会过期。需要重新调用订阅接口。另外，一次性订阅消息只能发送一次，如果用户再次触发相同模板，必须重新订阅。
**Q：iOS手机能收到消息，Android手机收不到。**
A：Android手机厂商（如华为、小米、OPPO）有自己的推送通道，微信消息可能被系统拦截。建议用户将微信加入“自启动”白名单，并关闭“省电模式”对微信的限制。
**Q：消息推送延迟严重，有时几小时才收到。**
A：微信服务器对普通小程序的消息推送有优先级限制，非实时消息可能排队。检查后台“开发” -> “开发管理” -> “消息推送”中的“消息频率”设置，确保没有触发频率限制。另外，避免在短时间内对同一用户发送多条消息。
---
**收尾总结**
通过以上五个步骤，你可以系统性地排查小程序消息收不到的问题。核心要点是：先确认后台配置正确，再验证服务器能正常接收和响应微信请求，然后检查用户订阅状态和手机权限，最后通过官方工具测试链路。建议每次修改配置后，都使用测试工具验证，避免遗漏。如果所有步骤都检查无误，但问题依然存在，可以联系微信开放平台客服，提供小程序的AppID和具体操作日志，官方会协助排查。日常运营中，建议在服务器代码中增加详细日志记录，并定期检查后台消息推送的调用量，避免超限导致服务中断。