微信公众号模板消息 notes 字段不显示问题排查与解决

问题描述

在使用微信公众号测试号发送模板消息时，遇到一个奇怪的问题：模板中定义了6个字段，但 notes（备注）字段始终不显示，其他5个字段都能正常显示。

模板内容如下：

1
姓名：{{name.DATA}}
2
电话：{{phone.DATA}}
3
时间：{{time.DATA}}
4
项目：{{services.DATA}}
5
员工：{{staff.DATA}}
6
备注：{{notes.DATA}}

API 调用返回成功，但微信消息中只显示前5行，备注始终不出现。

排查过程

1. 排除字段数量限制

最初怀疑是微信测试号有字段数量限制（最多5个字段）。通过测试发现：

• 去掉”员工”字段，只发5个字段 → 备注仍然不显示
• 添加更多字段到9个 → 所有字段包括备注都显示了

结论：不是字段数量限制。

2. 排除字符长度限制

根据微信官方文档，模板消息每行内容不超过20字符，总内容不超过200字符。测试数据远未超过限制。

结论：不是字符长度问题。

3. 发现关键规律

通过反复测试发现一个规律：

当 notes 是模板的最后一个字段时，它不会显示。

4. 验证 notes 字段名问题

将 notes 替换为其他字段名测试：

notes 和 remark 都不显示，而 info、message 可以正常显示。

原因分析

微信公众号模板消息 API 原本支持一个 remark 参数，用于在消息底部显示备注信息。但从 2023年3月30日 起，微信官方发布公告：

模板消息不再展示备注（remark）字段

微信对 notes、remark 等字段名进行了特殊处理，将其识别为”备注”类字段，因此不予显示。这是微信的保留字段名限制。

解决方案

方案一：更换字段名（推荐）

将 notes 改为其他名称，如 message、info、desc 等：

1
姓名：{{name.DATA}}
2
电话：{{phone.DATA}}
3
时间：{{time.DATA}}
4
项目：{{services.DATA}}
5
员工：{{staff.DATA}}
6
留言：{{message.DATA}}

方案二：在 notes 后添加占位字段

在 notes 后面添加一个占位字段，使其不再是最后一个字段：

1
姓名：{{name.DATA}}
2
电话：{{phone.DATA}}
3
时间：{{time.DATA}}
4
项目：{{services.DATA}}
5
员工：{{staff.DATA}}
6
备注：{{notes.DATA}}
7
其他：{{other.DATA}}

发送时 other 字段可以不传值或传空值。

代码修改

后端发送通知数据时，将字段名从 notes 改为 message：

1
// 注意：不能使用 notes 作为字段名，微信会将其识别为保留的"备注"字段而不显示
2
return {
3
  name,
4
  phone,
5
  time: timeRange,
6
  services,
7
  staff,
8
  message  // 原来是 notes
9
};

总结

1. 微信公众号模板消息有保留字段名限制，notes、remark 等会被识别为”备注”字段而不显示
2. 这是 2023 年微信政策调整的结果，模板消息不再展示备注内容
3. 解决方案是避免使用这些保留字段名，改用 message、info 等普通名称
4. 排查此类问题时，可以通过添加/删除字段、更换字段名等方式逐步定位

参考资料

• 微信公众平台模板消息接口文档
• 模板消息字数限制说明