微信公眾號測試賬號自定義菜單開發完整指南：按鈕類型、API 調用、Java 實現與調試技巧

前言

微信公眾號自定義菜單是用戶交互的核心入口。本文系統梳理 10 種按鈕類型、接口調用規範、參數說明、返回碼、Java 實體類設計、菜單構建與創建/查詢完整代碼，並提供測試賬號調試實戰技巧。

一、 10 種按鈕類型詳解

關鍵限制

• 3~8 華為型按鈕需微信 5.4+ 版本，舊版無響應、無事件推送。
• 9、10 僅供**未資質認證的訂閱號**使用，**無事件推送**，能力受限。
• 一級菜單 1~3 個，二級菜單 1~5 個。

二、 接口調用規範

• 請求方式：POST (HTTPS)
• 創建菜單：https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN
• 查詢菜單：https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN
• 刪除菜單：https://api.weixin.qq.com/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

請求示例 (click + view + 子菜單)

{
  "button": [
    {
      "type": "click",
      "name": "今日歌曲",
      "key": "V1001_TODAY_MUSIC"
    },
    {
      "name": "菜單",
      "sub_button": [
        { "type": "view", "name": "搜索", "url": "https://www.soso.com/" },
        { "type": "view", "name": "視頻", "url": "https://v.qq.com/" },
        { "type": "click", "name": "贊一下我們", "key": "V1001_GOOD" }
      ]
    }
  ]
}

參數說明

返回碼

• 成功：{"errcode":0,"errmsg":"ok"}
• 失敗示例：{"errcode":40018,"errmsg":"invalid button name size"}

三、 Java 實體類設計（對應 JSON 結構）

// 基礎按鈕
public class Button {
    private String type;
    private String name;
    private Button[] sub_button;
    // getter/setter 省略
}

// click 類按鈕
public class ClickButton extends Button {
    private String key;
    // getter/setter
}

// view 類按鈕
public class ViewButton extends Button {
    private String url;
    // getter/setter
}

// 菜單容器
public class Menu {
    private Button[] button;
    // getter/setter
}

四、 菜單構建與調用完整代碼

import net.sf.json.JSONObject;
import java.util.*;

public class WechatMenuUtil {
    private static final String CREATE_MENU_URL = "https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN";
    private static final String QUERY_MENU_URL = "https://api.weixin.qq.com/cgi-bin/menu/get?access_token=ACCESS_TOKEN";

    /** 構建測試菜單 */
    public static Menu initMenu() {
        Menu menu = new Menu();
        
        ClickButton clickBtn = new ClickButton();
        clickBtn.setType("click");
        clickBtn.setName("點擊測試");
        clickBtn.setKey("CLICK_TEST");
        
        ViewButton viewBtn = new ViewButton();
        viewBtn.setType("view");
        viewBtn.setName("跳轉百度");
        viewBtn.setUrl("https://www.baidu.com");
        
        ClickButton scanBtn = new ClickButton();
        scanBtn.setType("scancode_push");
        scanBtn.setName("掃碼測試");
        scanBtn.setKey("SCAN_TEST");
        
        ClickButton locBtn = new ClickButton();
        locBtn.setType("location_select");
        locBtn.setName("位置測試");
        locBtn.setKey("LOC_TEST");
        
        Button subContainer = new Button();
        subContainer.setName("更多功能");
        subContainer.setSub_button(new Button[]{scanBtn, locBtn});
        
        menu.setButton(new Button[]{clickBtn, viewBtn, subContainer});
        return menu;
    }

    /** 創建菜單 */
    public static int createMenu(String menuJson, String accessToken) {
        String url = CREATE_MENU_URL.replace("ACCESS_TOKEN", accessToken);
        JSONObject resp = HttpUtil.doPostStr(url, menuJson); // 需自行實現 HTTP POST
        return resp != null ? resp.getInt("errcode") : -1;
    }

    /** 查詢菜單 */
    public static JSONObject queryMenu(String accessToken) {
        String url = QUERY_MENU_URL.replace("ACCESS_TOKEN", accessToken);
        return HttpUtil.doGetStr(url); // 需自行實現 HTTP GET
    }
}

五、 測試入口

public class WechatMenuTest {
    public static void main(String[] args) {
        // 1. 獲取 access_token（需實現 WechatUtil.getAccessToken()）
        AccessToken token = WechatUtil.getAccessToken();
        System.out.println("accessToken: " + token.getToken());
        
        // 2. 構建菜單 JSON
        Menu menu = WechatMenuUtil.initMenu();
        JSONObject menuJson = JSONObject.fromObject(menu);
        System.out.println("菜單 JSON: " + menuJson.toString());
        
        // 3. 創建菜單
        int result = WechatMenuUtil.createMenu(menuJson.toString(), token.getToken());
        if (result == 0) {
            System.out.println("菜單創建成功！");
        } else {
            System.out.println("創建失敗，錯誤碼: " + result);
        }
        
        // 4. 查詢驗證
        JSONObject queried = WechatMenuUtil.queryMenu(token.getToken());
        System.out.println("查詢結果: " + queried);
    }
}

六、 實戰調試技巧

1. 使用測試賬號：https://mp.weixin.qq.com/debug/cgi-bin/sandbox?t=sandbox/login 獲取測試 appid/secret，每日可重置。
2. 菜單生效延遲：創建後需**退出公眾號會話列表重新進入**，或拉下刷新會話列表才可見新菜單。
3. URL 編碼：view 類 url 若帶參數，需 URLEncoder.encode，且域名需在公眾號後台「業務域名」白名單中。
4. 事件接收驗證：配置開發者服務器 URL，使用 ngrok/內網穿透測試本地接收 click 事件推送。
5. 素材管理：media_id 型按鈕需先調用「新增永久素材」接口上傳圖文/圖片，獲取合法 media_id。

七、 常見錯誤碼速查

八、 總結

微信自定義菜單開發核心在於：

1. 準確選擇按鈕類型，匹配業務場景與用戶微信版本。
2. 嚴格遵循 JSON 結構、字段長度、必填規則構建請求體。
3. 妥善管理 access_token（緩存、定時刷新、併發安全）。
4. 善用測試賬號與 ngrok 進行本地端到端調試。
5. 關注菜單生效延遲、域名白名單、素材預上傳等運維細節。

菜單是公眾號的「臉面」，頻繁變更會影響用戶肌肉記憶。建議建立菜單版本管理，灰度發布，監控點擊事件數據，持續優化信息架構。