Halo CMS对接微信公众号，内容同步推送
如果你正在使用 Halo CMS 搭建博客，同时希望把新文章自动推送到微信公众号，那么这篇文章就是为你准备的。
下面会从零开始，讲清楚如何通过微信公众平台的接口和 Halo 的插件或自定义配置，完成内容同步推送。
整个过程不依赖复杂开发，按照步骤操作即可看到效果。
准备工作：公众号与 Halo 后台的必备条件
开始配置前，需要确认几个前提。
首先，你的微信公众号必须是已认证的服务号，因为只有服务号才能使用高级群发接口和素材管理接口。
订阅号无法直接调用这些接口实现自动推送。
其次，Halo 版本建议在 2.x 及以上，并确保服务器可以正常访问外网，特别是微信 API 的域名 api.weixin.qq.com。
在微信公众平台后台，进入“开发”->“基本配置”，记录下 AppID 和 AppSecret。
同时，在“IP白名单”中填入你 Halo 服务器所在的公网 IP，否则接口调用会返回 40164 错误。
配置 Halo 与微信接口的对接参数
Halo 本身没有内置的微信公众号推送功能，通常有两种实现方式：使用第三方插件（如 halo-plugin-wechat）或通过自定义 API 结合定时任务。
这里以插件方式为例，因为它对新手更友好。
登录 Halo 后台，进入“插件”市场，搜索“微信”或“WeChat”，找到支持公众号同步的插件并安装。
安装完成后，在插件设置页面填写之前获取的 AppID 和 AppSecret。
部分插件还需要填写 Token 和 EncodingAESKey，这些可以在微信公众平台的“基本配置”中生成。
如果插件不可用，也可以手动配置。
在 Halo 的 application.yaml 中添加自定义配置项，然后编写一个简单的定时任务，通过微信的“新增草稿”接口 https://api.weixin.qq.com/cgi-bin/draft/add 推送文章。
下面是一个配置片段示例：
wechat:
app-id: your_app_id
app-secret: your_app_secret
template-id: your_template_id实现文章发布后自动同步推送
配置好参数后，需要设置触发条件。
大多数插件会提供“发布时同步”选项，勾选后，每当你在 Halo 中发布新文章，插件会自动调用微信接口，将文章标题、封面、摘要和正文转换为公众号草稿。
注意，微信要求正文中的图片必须上传到微信素材库，因此插件通常会自动处理图片上传，但需要你的服务器能正常下载原图。
如果使用自定义方案，可以在 Halo 的 Content 发布事件中监听，然后调用微信接口。
关键步骤包括：获取 access_token（有效期 7200 秒，需缓存）、上传封面图为永久素材、构造图文消息并创建草稿。
以下是一个简单的验证命令，用于检查 access_token 是否获取成功：
curl -s "https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET"返回结果中如果包含 access_token 字段，说明配置正确。
之后在 Halo 发布一篇文章，观察微信公众平台的“草稿箱”是否出现新草稿。
常见报错与避坑指南
对接过程中最容易遇到两个问题。
一是 invalid ip 错误，原因是服务器 IP 未加入微信白名单，解决方法是登录公众平台，在“基本配置”->“IP白名单”中添加服务器公网 IP。
二是 40001 错误，表示 AppSecret 不正确或已重置，需要重新生成并更新 Halo 中的配置。
另外，微信对群发接口有频率限制，服务号每月只能群发 4 次，但创建草稿没有次数限制。
因此，建议将同步推送设置为“创建草稿”，然后手动在公众号后台群发，这样更灵活。
还要注意，文章中的外链会被微信过滤，只有白名单域名下的链接才能点击，所以正文中尽量使用公众号文章链接或纯文本。
验证同步效果与后续调整
完成配置后，在 Halo 中发布一篇测试文章，标题和内容都包含唯一标识，比如“测试同步-2025”。
等待几秒后，登录微信公众平台，进入“草稿箱”，查看是否有对应草稿。
如果有，说明同步成功；
如果没有，检查 Halo 日志中的错误信息，通常会有微信接口返回的具体错误码。
同步成功后，你还可以在插件中设置自动群发或定时群发，但注意遵守微信运营规范。
如果文章包含视频或音频，需要单独上传到微信素材库，插件可能不支持自动处理，建议手动操作。
总结：Halo CMS 对接微信公众号实现内容同步推送，核心是获取接口权限、配置参数、处理图片和触发时机。
只要 IP 白名单和 AppSecret 正确，整个流程可以稳定运行。
遇到报错时，优先查看微信返回的错误码，再对照官方文档排查。
常见疑问
问：订阅号可以对接吗？
订阅号没有群发接口权限，无法直接同步推送。如果只是想把文章链接放到公众号菜单，可以通过自定义菜单跳转，但不算内容同步。
问：同步推送会消耗微信接口调用次数吗？
创建草稿接口每天有调用上限，具体额度以微信官方文档为准。一般个人使用不会超限，但建议不要频繁重复推送同一篇文章。
问：图片同步失败怎么办？
检查图片链接是否可公开访问，微信要求图片格式为 jpg/png，且大小不超过 2MB。如果图片在本地服务器，需要确保外网能下载。
