用article-tools对接微信接口的完整指南:IP白名单、40164错误与access_token缓存详解
用article-tools对接微信接口的完整指南:IP白名单、40164错误与access_token缓存详解
article-tools 是一套轻量的封面制作与微信公众号、X 排版工具集,零依赖、浏览器打开即用。其中「发布到草稿」功能会调用微信接口把排好版的文章推送到公众号草稿箱,很多新手第一次对接就卡在 40164 错误上。本文完整讲解 IP 白名单配置、access_token 缓存机制和常见错误码排查方法,帮你一次性跑通发布流程。
article-tools 是什么?先看工具箱全貌
article-tools 包含四个各做一件事的小工具:
| 工具 | 文件 | 用途 |
|---|---|---|
| 封面生成器 | cover.html | 生成公众号封面图,支持配色、装饰、字体与素材图 |
| 二维码生成 | qrcode.html | 生成带 Logo 的二维码 |
| MD → 微信排版 | md-to-wechat.html | Markdown 转公众号富文本 |
| MD → X 排版 | md-to-x.html | Markdown 转 X 长文格式 |
前三个工具纯前端,双击 HTML 即可用。而「发布到公众号草稿箱」需要配合本地小服务 server/publish-wechat.mjs 来调用微信接口——它就是本文的主角。
对接微信接口前的两个前提条件
① 公众号必须是「已认证」的服务号 / 订阅号,且开通了草稿接口权限。未认证的个人订阅号调不了 draft/add,会报 48001。
② 配置 IP 白名单:调用微信接口的机器出口 IP 必须加进公众号后台「设置与开发 → 基本配置 → IP 白名单」。
快速查询本机公网出口 IP
本地运行时,微信看到的不是你内网地址,而是网络出口 IP:
- 浏览器搜索「我的 IP」,显示的公网地址就是出口 IP;
- 登录公众号后台 → 设置与开发 → 基本配置 → IP 白名单,把该 IP 添加进去(每行一个 IP);
- ⚠️ 家庭宽带 / 4G 网络的出口 IP 可能动态变化,IP 变动后需要重新添加,否则又会触发 40164。
配置并启动发布服务
服务零依赖,只需 Node ≥ 18。在 server/ 目录下:
cd server
cp .env.example .env # 编辑 .env,填写 AppID / AppSecret / 封面
npm start # 或:node publish-wechat.mjs
.env 配置项如下(详见 server/README.md):
| 变量 | 必填 | 说明 |
|---|---|---|
WECHAT_APPID |
✅ | 公众号开发者 ID |
WECHAT_APPSECRET |
✅ | 开发者密码 |
WECHAT_THUMB_MEDIA_ID |
二选一 | 已上传的永久素材 media_id,作封面 |
WECHAT_DEFAULT_COVER |
二选一 | 本地封面图路径,首次自动上传并缓存 media_id |
WECHAT_AUTHOR |
可选 | 默认作者名(≤8 字) |
PORT |
可选 | 默认 3007 |
封面是
draft/add的必填项。两个封面变量都不填时,服务会用正文里的第一张图当封面;正文也没图则报错。
启动后务必通过本地服务地址打开工具:http://127.0.0.1:3007/md-to-wechat.html。这样「发布到草稿」是同源请求,不会有跨域或混合内容问题;用 file:// 直接打开时按钮会提示你先走本地服务。
在工具里粘好 Markdown、选好风格,点击右上角「发布到草稿」,即可去公众号后台草稿箱查看结果。
access_token 缓存机制详解
微信接口的调用凭证 access_token 有明确的缓存策略,理解它能帮你判断「为什么有时报错、有时正常」:
- 有效期 7200 秒:服务用 AppID/Secret 向
cgi-bin/token换取 token 后,会在内存中缓存,2 小时内复用,不会每次发布都重新申请; - 提前 5 分钟刷新:代码按
expires_in - 300计算过期时间(见 server/publish-wechat.mjs),避免用旧 token 撞上微信的过期窗口; - 封面 media_id 落盘缓存:
WECHAT_DEFAULT_COVER首次上传后,media_id 连同文件修改时间一起写入.cache.json,封面图没改就不重复上传; - 安全考虑:
.env与.cache.json均在.gitignore中,不会被提交到仓库;服务只监听127.0.0.1,仅本机可访问。
40164 错误详解与常见错误码速查
40164 是新手最常见的报错,含义只有一个:调用来源 IP 不在白名单里。
- 确认你查的是「公网出口 IP」而不是内网 IP(如 192.168.x.x);
- 家庭网络重启路由器后 IP 可能变化,重新查一次再加;
- 白名单加的是「调接口的机器」的 IP,也就是运行
npm start的那台电脑。
服务内置了错误码友好提示(server/publish-wechat.mjs),完整对照表如下:
| errcode | 含义 / 处理 |
|---|---|
| 40164 | 出口 IP 不在白名单 → 去公众号后台加 IP |
| 40001 | AppSecret 不对,或 access_token 失效 |
| 40013 | AppID 不对 |
| 41001 | 缺少 access_token |
| 45009 | 触发接口频率限制,稍后再试 |
| 48001 | API 未授权 → 账号多半未认证 |
| 53500 | 发布能力被封禁 |
一键发布到草稿:完整工作流程
点击「发布到草稿」后,服务在后台自动完成四步:
- 换取并缓存 access_token(2 小时内复用);
- 图片转微信域名:把正文里的
data:内联图和外部链接图片逐张上传(uploadimg接口不占素材配额),替换成mmbiz.qpic.cn的 URL——不替换的话微信会直接丢图; - 解析封面
thumb_media_id:优先用正文指定的封面 →WECHAT_THUMB_MEDIA_ID→WECHAT_DEFAULT_COVER(自动上传缓存)→ 正文第一张图; - 调用
draft/add创建草稿,返回media_id,前端提示「✓ 已进草稿箱」。
两个安全设计值得一提:
- 只建草稿,不群发:即使误点「发布到草稿」,文章也只进草稿箱,绝不会推给粉丝;
- 服务仅监听本机:
127.0.0.1绑定,外部无法访问你的发布服务。
总结
对接 article-tools 与微信接口其实只有三件事:认证公众号 + 加 IP 白名单、配好 .env 并通过 127.0.0.1:3007 打开工具、理解 access_token 缓存与错误码。遇到 40164 先查出口 IP,遇到 48001 先查认证状态,对照上面的错误码表基本可以覆盖所有新手问题。跑通一次之后,写文章、出封面、排公众号版、进草稿箱,全程只需要点鼠标。


