用article-tools对接微信接口的完整指南:IP白名单、40164错误与access_token缓存详解

原创2026-10-25 23:34:212,693 阅读

用article-tools对接微信接口的完整指南:IP白名单、40164错误与access_token缓存详解

article-tools 是一套轻量的封面制作与微信公众号、X 排版工具集,零依赖、浏览器打开即用。其中「发布到草稿」功能会调用微信接口把排好版的文章推送到公众号草稿箱,很多新手第一次对接就卡在 40164 错误上。本文完整讲解 IP 白名单配置、access_token 缓存机制和常见错误码排查方法,帮你一次性跑通发布流程。

article-tools 是什么?先看工具箱全貌

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:

  1. 浏览器搜索「我的 IP」,显示的公网地址就是出口 IP;
  2. 登录公众号后台 → 设置与开发 → 基本配置 → IP 白名单,把该 IP 添加进去(每行一个 IP);
  3. ⚠️ 家庭宽带 / 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:// 直接打开时按钮会提示你先走本地服务。

md-to-wechat 微信公众号排版工具与发布到草稿按钮

在工具里粘好 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 发布能力被封禁

一键发布到草稿:完整工作流程

点击「发布到草稿」后,服务在后台自动完成四步:

  1. 换取并缓存 access_token(2 小时内复用);
  2. 图片转微信域名:把正文里的 data: 内联图和外部链接图片逐张上传(uploadimg 接口不占素材配额),替换成 mmbiz.qpic.cn 的 URL——不替换的话微信会直接丢图;
  3. 解析封面 thumb_media_id:优先用正文指定的封面 → WECHAT_THUMB_MEDIA_ID → WECHAT_DEFAULT_COVER(自动上传缓存)→ 正文第一张图;
  4. 调用 draft/add 创建草稿,返回 media_id,前端提示「✓ 已进草稿箱」。

article-tools 封面生成器配色与封面预览界面

两个安全设计值得一提:

  • 只建草稿,不群发:即使误点「发布到草稿」,文章也只进草稿箱,绝不会推给粉丝;
  • 服务仅监听本机:127.0.0.1 绑定,外部无法访问你的发布服务。

总结

对接 article-tools 与微信接口其实只有三件事:认证公众号 + 加 IP 白名单、配好 .env 并通过 127.0.0.1:3007 打开工具、理解 access_token 缓存与错误码。遇到 40164 先查出口 IP,遇到 48001 先查认证状态,对照上面的错误码表基本可以覆盖所有新手问题。跑通一次之后,写文章、出封面、排公众号版、进草稿箱,全程只需要点鼠标。

登录后查看全文
article-tools