微信公众号自定义菜单开发实战指南

微信公众号的自定义菜单是用户进入公众号后最先看到的交互入口，它直接影响用户的第一印象和后续操作路径。很多开发者第一次接触公众号开发时，都会卡在菜单配置这一步——要么是接口调用报错，要么是菜单不生效，要么是类型搞混。这篇文章结合我在多个项目中的实战经验，把自定义菜单的开发流程、常见坑点和实用技巧一次讲清楚。

一、自定义菜单的基本能力

微信公众平台为认证的服务号和订阅号开放了自定义菜单接口。菜单结构最多支持3个一级菜单，每个一级菜单下最多5个二级菜单。菜单项支持以下类型：

• click：点击推事件，用户点击后微信服务器推送事件到开发者服务器
• view：跳转URL，用户点击后打开指定网页
• miniprogram：跳转小程序，需要关联小程序并指定appid和pagepath
• scancode_push / scancode_waitmsg：扫码相关事件
• pic_photo_or_album：弹出拍照或相册
• location_select：弹出地理位置选择器

其中click、view、miniprogram是最常用的三种类型，覆盖了绝大多数业务场景。

二、开发前的准备工作

在写代码之前，需要确认几件事：

• 公众号已认证，且获取了AppID和AppSecret
• 服务器已配置好IP白名单，否则调用接口会返回40164错误
• 已经获取到access_token，这是调用所有微信接口的凭证

access_token的有效期是7200秒，且微信对获取频率有限制，建议用中控服务器统一获取和刷新，不要每次请求都重新获取。

三、核心接口调用

自定义菜单的创建、查询、删除分别对应三个接口：

POST https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
GET  https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN
GET  https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

创建菜单时，请求体是一个JSON结构。下面是一个包含三种常见类型的完整示例：

{
  "button": [
    {
      "type": "click",
      "name": "今日推荐",
      "key": "TODAY_RECOMMEND"
    },
    {
      "name": "服务",
      "sub_button": [
        {
          "type": "view",
          "name": "个人中心",
          "url": "https://yourdomain.com/profile"
        },
        {
          "type": "miniprogram",
          "name": "小程序商城",
          "url": "https://yourdomain.com/fallback",
          "appid": "wx1234567890abcdef",
          "pagepath": "pages/index/index"
        }
      ]
    },
    {
      "type": "view",
      "name": "官网",
      "url": "https://yourdomain.com"
    }
  ]
}

注意几个细节：

• name字段不超过16个字节，中文算3个字节，所以最多5个汉字
• view类型的url必须是完整URL，且域名需要在公众号后台配置为业务域名
• miniprogram类型必须同时提供url作为兜底，当用户微信版本过低不支持小程序时跳转该链接
• 一级菜单和二级菜单不能混用，一个一级菜单要么自己有点击行为，要么只作为容器

四、事件推送与业务处理

当用户点击click类型菜单时，微信服务器会向你的服务器推送一个XML格式的事件消息：

<xml>
  <ToUserName><![CDATA[gh_xxxxx]]></ToUserName>
  <FromUserName><![CDATA[oUserOpenId]]></FromUserName>
  <CreateTime>1700000000</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[CLICK]]></Event>
  <EventKey><![CDATA[TODAY_RECOMMEND]]></EventKey>
</xml>

你需要在消息处理逻辑中根据EventKey分发到不同的业务处理函数。如果是view类型，微信不会推送事件，用户直接打开网页；如果是miniprogram类型，也不会推送事件，用户直接进入小程序页面。

五、常见坑点与排查建议

• 菜单不生效：先检查是否调用了创建接口并返回errcode:0，再确认公众号是否已认证。未认证的订阅号无法使用自定义菜单接口。
• 菜单更新延迟：菜单创建后并非立即对所有用户生效，通常需要几分钟，建议用menu/get接口确认当前生效的菜单结构。
• access_token冲突：如果多个服务同时获取token，会导致旧token失效。务必用中控服务统一管理。
• URL域名校验失败：view类型菜单的URL域名必须是已备案且配置在“网页授权域名”或“业务域名”中的域名。
• 个性化菜单：如果希望不同用户看到不同菜单，可以使用menu/addconditional接口，根据用户标签、性别、地区等条件展示差异化菜单。

六、小结

微信公众号自定义菜单的开发并不复杂，核心就是获取access_token → 构造JSON → 调用创建接口 → 处理事件推送这条链路。真正容易出问题的地方在于token管理、域名配置和类型细节。建议在开发阶段先用menu/get接口确认菜单结构，再逐步替换为正式配置。如果业务需要更灵活的入口，可以结合个性化菜单和模板消息，把菜单作为流量分发的中枢来设计。