自动化发布微信公众号文章，听起来很简单——调几个 API，传点参数，搞定。
实际上手后发现，微信的开发者文档更新不及时，错误信息暧昧，还有些根本说不清的玄学 BUG。这篇文章记录我在打通公众号发布流程时遇到的三个核心坑。
坑一：add_news 已废弃，draft/create 返回 40066
最早查文档，创建图文素材用的是 cgi-bin/material/add_news。
发出去直接返回：
{"errcode":45106, "errmsg": "This API has been unsupported."}45106：此接口已不再支持，请改用 draft 相关接口。
OK，换 cgi-bin/draft/create。同一个请求体，把 endpoint 换掉再试。
返回：
{"errcode":40066, "errmsg": "invalid url"}40066 的错误描述是「不合法的 URL」。第一反应是请求体里某个 URL 参数不对。检查了几遍——content_source_url 传的是空字符串，content 里也没有链接。换了纯英文内容、去掉图片、去掉摘录，全部返回同样的错误。
折腾半天，无意中试了个拼写变体：draft/add。
{"media_id": "xxx...", "item": []}成功了。
正确的端点不是 draft/create，而是 draft/add。部分微信公众号的接口文档里写的是 create，但实际有效的是 add。两个端点都能响应、都返回错误信息，但只有一个能真正创建草稿。
坑二：add_material 上传图片返回正确，但素材列表查不到
上传封面图片用的是 cgi-bin/material/add_material，返回了 media_id。紧接着用 batchget_material 查素材列表，确实能查到。
但拿去创建草稿时，一直报 40066。排查到最后发现：问题不在图片，而在于 draft/create 这个接口本身（见坑一）。换了 draft/add 后同样的 media_id 直接通过。
所以如果你确认图片上传成功、media_id 有效，但草稿创建一直失败，先检查 endpoint 对不对。
坑三：45003 title size out of limit——标题字节玄学
这是最让人抓狂的一个。
所有参数都对了，心想写 5 篇文章的草稿应该没问题。结果第一篇就返回：
{"errcode":45003, "errmsg": "title size out of limit"}我的标题只有 10 个中文字符，怎么超限？
开始逐个排查：
- “多平台网站托管排查实战”（11 字 / 33 字节）→ ❌
- “平台网站托管排查实战”（10 字 / 30 字节）→ ✅
- “多平台网站托管排查战”（10 字 / 30 字节）→ ✅
- “多平台网站托管排查实战a”（加一个 ascii 字符）→ ❌
发现规律了：33 字节以上的标题会触发这个错误，但 30 字节就正常。关键是 30-32 字节之间没有明确的分界线，某些 33 字节的组合能过，某些不能。
更诡异的是字符组合依赖。同一个 11 字标题，改一个字就能过：
- “多平台网站托管排查实战” → ❌
- “平台网站托管排查实战”（去掉「多」）→ ✅
- “多平台网站托管排查战”（去掉「实」）→ ✅
但 “平台网站托管排查实战” 这个 10 字版本又完全正常。说明微信 API 对标题的校验不是简单的字节数检查，而是基于某种字节模式匹配，特定顺序的 UTF-8 序列会触发 bug。
最终解决方案：标题控制在 30 字节以内（约 10 个中文字符或 30 个 ASCII 字符），避开中文冒号和特定字符组合。如果某个标题报错，删一个字或换顺序再试。
坑四：个人订阅号的 API 权限冰山
过程中还发现，未认证的个人订阅号 API 权限非常有限。尝试获取用户列表、群发消息等接口时，返回：
{"errcode":48001, "errmsg": "api unauthorized"}这意味着：
- 可以创建草稿 ✅
- 可以上传素材 ✅
- 可以获取素材列表 ✅
- 不能自动发布（
freepublish/submit可能受限） - 不能获取用户列表
- 不能群发消息
- 所有涉及粉丝和推送的接口都不可用
所以如果你的是个人订阅号，API 的实际可用范围比文档写的窄很多。草稿管理是能用的最大范围，发布那一步还是得手动到公众号后台点一下。
汇总：正确的微信公众号文章发布流程
把坑都踩一遍后，总结一个能跑通的流程：
| 步骤 | API | 备注 |
|---|---|---|
| 1. 上传封面图片 | material/add_material | POST，type=image，用 form-data |
| 2. 创建草稿 | draft/add ✅（不是 draft/create） | JSON body，标题 ≤30 字节 |
| 3. 查看草稿 | draft/get / draft/batchget | 返回 media_id 列表 |
| 4. 发布 | 需手动操作 | 个人号：后台「发布」按钮 |
| 5. 管理已发布 | freepublish/batchget | 查询已发布文章 |
关键教训
- 不要完全信任官方文档。
draft/create就是文档里写的，但实际不能用的。试错时多试几个 endpoint 变体。 - 错误信息可能完全误导。40066「invalid url」和标题、URL 都没关系，问题在 endpoint 本身。
- 标题校验有玄学。如果报 45003，先缩短到 30 字节以内，还不过就换字换顺序。
- 个人号的边界要清楚。先确认你的账号类型能调哪些 API，避免花时间在不可用的接口上。
- API 探针先行。正式创建内容前，先发一个极简 payload 测试接口是否可用，不要直接上完整文章。
微信的开发者生态一直以「文档滞后、错误信息暧昧」闻名。这次经历算是深度体验了一把。如果你也在接公众号 API，希望这篇能帮你少走弯路。