geekjourneyx__md2wechat-skill/docs/WECHAT-CREDENTIALS.md

微信凭证与 IP 白名单指南

这份文档专门解决 4 个最常见的问题：

1. WECHAT_APPID 和 WECHAT_SECRET 去哪里拿
2. 为什么明明填了凭证，调用微信接口还是失败
3. 微信接口 IP 白名单在哪里配
4. 配好之后，怎么写回 md2wechat 并验证

如果你是第一次接触微信公众号开发，按这份文档一步一步做就够了。

扩展阅读：

• 微信开发者平台：https://developers.weixin.qq.com/platform
• 参考文章：https://www.md2wechat.com/zh/blog/wechat-appid-appsecret-guide

先知道两件事

1. AppID 和 AppSecret 是什么

• AppID：你的公众号在微信侧的唯一标识
• AppSecret：你的公众号调用微信接口时使用的密钥

md2wechat 在以下场景会用到它们：

• 上传图片到微信素材库
• 创建微信草稿
• 创建图片消息

2. 为什么还需要 IP 白名单

微信不是只看 AppID 和 AppSecret。
对于很多接口，它还要求“发请求的机器公网 IP”必须在微信后台白名单里。

所以你会遇到这种情况：

• AppID 和 AppSecret 明明没填错
• 但接口仍返回：

ip xxx.xxx.xxx.xxx not in whitelist

这不是 md2wechat 代码问题，而是微信的前置安全限制。

---

一、如何获取 AppID 和 AppSecret

步骤 1：登录微信开发者平台

打开：

https://developers.weixin.qq.com/platform

使用你的公众号管理员微信扫码登录。

注：仓库现有文档和用户反馈表明，开发接口管理入口已经迁移到微信开发者平台，不要再只去旧版公众号后台里找。

步骤 2：选择你的公众号

登录后，选择你要接入 md2wechat 的那个公众号。

如果你有多个公众号，注意不要选错。

步骤 3：进入“开发接口管理”

进入公众号后，找到：

• 开发接口管理

不同时间点微信后台文案可能略有变化，但核心目标是进入能看到开发者 ID 和开发者密码的页面。

步骤 4：复制 AppID

在开发接口管理页面，找到：

• 开发者ID(AppID)

直接复制保存。

步骤 5：获取 AppSecret

在同一页面，找到：

• 开发者密码(AppSecret)

通常需要点击：

• 重置

然后完成管理员验证后，微信会给你新的 AppSecret。

注意：

• AppSecret 很重要，不要发给别人
• 不要提交到 Git 仓库
• 如果你点击了“重置”，旧的 AppSecret 会失效

---

二、把凭证写到 md2wechat

推荐方式是写配置文件。

步骤 1：生成配置文件

md2wechat config init

默认配置文件路径：

~/.config/md2wechat/config.yaml

步骤 2：填入微信配置

打开配置文件，填写：

wechat:
  appid: "你的公众号 AppID"
  secret: "你的公众号 AppSecret"

如果你更喜欢环境变量，也可以：

export WECHAT_APPID="你的公众号 AppID"
export WECHAT_SECRET="你的公众号 AppSecret"

如果你需要管理多个公众号，可以使用命名账号：

wechat:
  default_account: main
  accounts:
    main:
      appid: "主公众号 AppID"
      secret: "主公众号 AppSecret"
    client-a:
      appid: "客户 A AppID"
      secret: "客户 A AppSecret"

执行上传或草稿类命令时可显式选择：

md2wechat convert article.md --draft --cover cover.jpg --wechat-account client-a

命名账号属于高级 API 功能。使用命名账号执行微信副作用前，CLI 会要求 MD2WECHAT_API_KEY 有效；本地查看命令不联网：

md2wechat config wechat-accounts --json

完整的单账号、多账号、API key 边界和排障流程见 配置保姆级指南。

步骤 3：验证配置是否生效

md2wechat config validate
md2wechat config show --format json
md2wechat config wechat-accounts --json

你应该重点确认：

• config_file
• wechat.appid
• 当前是不是你预期的配置文件

---

三、如何配置微信接口 IP 白名单

什么时候必须配

如果你要做这些事，就要高度怀疑自己需要白名单：

• md2wechat upload_image
• md2wechat convert --upload
• md2wechat convert --draft
• md2wechat create_image_post
• md2wechat test-draft

白名单报错长什么样

最常见的报错形态：

ip xxx.xxx.xxx.xxx not in whitelist

或类似含义的微信错误。

步骤 1：先查出当前执行机的公网 IP

在你实际运行 md2wechat 的那台机器上执行：

curl ifconfig.me

如果不可用，也可以试：

curl ip.sb
curl ipinfo.io/ip

一定要在“实际发起微信请求的机器”上执行。

例如：

• 你在本地电脑运行，就查本地电脑当前公网 IP
• 你在云服务器运行，就查云服务器公网 IP
• 你在 CI 里运行，就查 CI 出口 IP

步骤 2：回到微信开发者平台

仍然进入：

• 公众号
• 开发接口管理

步骤 3：找到“IP 白名单”

在开发接口管理页面中找到：

• IP白名单

然后点击：

• 设置 或
• 修改

步骤 4：把公网 IP 加进去

把刚刚查到的公网 IP 填进去。

如果你有多个固定出口 IP，可以一起填。通常多个 IP 可按页面提示分隔填写。

步骤 5：保存并等待几分钟

白名单往往不是瞬间生效，通常建议：

• 等 1 到 5 分钟
• 然后再重试上传或建草稿

---

四、最常见的坑

1. 本地电脑和服务器不是同一个 IP

很多人会在本地查出一个 IP，结果程序实际跑在云服务器上。
这样加到白名单里当然没用。

记住一句话：

白名单里要加的是“真正发微信请求的那台机器的公网 IP”。

2. 公司网络 / 家庭宽带 IP 会变

如果你是在家里电脑或公司网络环境里跑：

• 路由器重连后公网 IP 可能变化
• 运营商也可能重新分配出口 IP

这时你昨天能用，今天突然白名单报错，是正常现象。

3. GitHub Actions / 动态云环境不适合直接调微信

如果运行环境 IP 不固定，白名单维护会很痛苦。
这种场景更适合：

• 固定一台有公网 IP 的服务器
• 或固定出口网关

4. 使用高级版 API 固定出口

如果你不能直接在运行 md2wechat 的机器上获得固定公网 IP，可以使用高级版 API 服务的微信固定出口能力。它提供稳定的微信接口出口 IP，解决动态 IP 导致微信后台白名单反复更新的问题。

开通后，你会拿到两项信息：

• 完整的 proxy_url
• 需要填写到微信后台 IP 白名单 的固定出口 IP

配置文件写法：

wechat:
  proxy_url: "https://wechat-egress-url-provided-by-md2wechat.example"

也可以用环境变量临时覆盖：

export WECHAT_PROXY_URL="https://wechat-egress-url-provided-by-md2wechat.example"

config show --format json 中对应字段是 wechat_proxy_url；默认会隐藏代理密码。

这个代理只影响微信上传、建草稿和图片消息发送，不影响 API 排版、图片生成 provider、主题/提示词发现或普通转换。启用代理模式后，执行 upload_image、convert --draft、convert --upload 或 create_image_post 前需要有效的 MD2WECHAT_API_KEY。

微信后台 IP 白名单 应填写高级版 API 服务提供的固定出口 IP。不要自行拼接代理主机、端口或部署形态；以服务侧提供的完整 URL 为准。需要开通固定出口能力或企业私有化方案时，请联系作者进行 API咨询。HTTPS_PROXY 只能作为全局代理兜底背景，优先使用 wechat.proxy_url / WECHAT_PROXY_URL，避免把非微信流量一起代理。

5. 重置 AppSecret 后忘了更新配置

一旦你在微信后台点击了 重置：

• 旧 AppSecret 会失效
• 你必须同步更新 ~/.config/md2wechat/config.yaml 或环境变量

---

五、推荐的最小验证顺序

配置完成后，建议按这个顺序测：

1. 先验证配置

md2wechat config validate

2. 再试单张图片上传

md2wechat upload_image ./cover.png --json

如果这一步失败，优先排查：

• AppID / AppSecret
• IP 白名单
• 图片格式

3. 再试建草稿

md2wechat test-draft ./article.html ./cover.png --json

4. 最后再跑完整主链

md2wechat convert article.md --upload --draft --cover cover.png --json

---

六、遇到问题先看什么

报 WECHAT_APPID is required

先看：

• CONFIG.md
• TROUBLESHOOTING.md

报 ip not in whitelist

先看：

• 本文档的“如何配置微信接口 IP 白名单”
• FAQ.md
• SMOKE.md

不确定现在到底用了哪份配置

执行：

md2wechat config show --format json

重点看：

• config_file
• 当前 md2wechat_base_url
• 当前图片 provider

---

七、给新手的最终建议

如果你只想最快跑通，不要一上来就调完整链路。

按这个最稳：

1. 拿到 AppID 和 AppSecret
2. 写进 ~/.config/md2wechat/config.yaml
3. 查当前执行机公网 IP
4. 把公网 IP 加到微信开发者平台白名单
5. 先测 upload_image
6. 再测 test-draft
7. 最后测 convert --draft

这样定位问题最快，也最不容易把“配置错”“白名单错”“图片错”混在一起。