微信公眾號開發十大坑實戰避雷指南（下）：菜單回覆、網頁授權、圖片上傳、H5 返回刷新

接上篇，本文繼續深入微信公眾號開發實戰中的核心坑點：XML 菜單事件處理、網頁授權雙模式、JS-SDK 圖片上傳 iOS 遞歸兼容、H5 頁面返回刷新、微信內關閉窗口等，附生產級 C# 代碼（邏輯通用，PHP/Java 同理）。

第六坑：菜單事件 XML 中 ToUserName/FromUserName 反了

微信推送 XML：ToUserName = 公眾號 ID，FromUserName = 用戶 OpenID。
回覆 XML 必須互換：ToUserName = 用戶 OpenID，FromUserName = 公眾號 ID。
寫反 = 用戶收不到消息，後台無報錯，極難排查。

// 正確回覆 XML 構造
string xml = $@"
       
       
    {timestamp}
    
    
";

第七坑：回覆邏輯必須在服務器驗證通過後掛載

微信服務器驗證（GET 請求驗證 signature）通過後，才會推送 POST 事件。
若在驗證階段就輸出回覆 XML，會導致驗證失敗。
正確位置：驗證通過的分支中處理 POST 請求並輸出回覆。

第八坑：菜單 JSON 中 URL 必須帶協議頭 https://

自定義菜單接口："url": "https://your.com/page"。
缺少 https:// 會導致菜單發布失敗或點擊無反應。
特別注意：JS-SDK 安全域名配置不需要協議頭，菜單 URL必須帶協議頭。

第九坑：iOS 微信圖片上傳不支援 for 循環，必須遞歸鏈式調用

現象：Android 可 for (id of ids) wx.uploadImage(id)，iOS 只能上傳最後一張。
原因：iOS 微信 WebView 並發限制，需串行上傳。

錯誤寫法（iOS 失效）

// ❌ iOS 只會上傳最後一張
localIds.forEach(id => {
    wx.uploadImage({ localId: id, success: res => uploadServer(res.serverId) });
});

正確寫法：遞歸鏈式（全平台通用）

function uploadChain(localIds, index = 0) {
    if (index >= localIds.length) return;
    
    wx.uploadImage({
        localId: localIds[index],
        isShowProgressTips: 1,
        success: res => {
            uploadServer(res.serverId).then(() => {
                uploadChain(localIds, index + 1); // 成功後遞歸下一張
            });
        },
        fail: err => {
            console.error('上傳失敗', err);
            uploadChain(localIds, index + 1); // 失敗也繼續下一張
        }
    });
}

// 調用入口
wx.chooseImage({
    count: 9,
    success: res => {
        let ids = res.localIds;
        // 兼容 iOS 大小寫 bug
        if (typeof ids === 'string') ids = ids.replace('wxlocalresource', 'wxLocalResource').split(',');
        uploadChain(ids);
    }
});

第十坑：JS-SDK 簽名 URL 必須是「當前頁完整 URL，去除 # 及後」

// PHP 端生成簽名時
$url = 'https://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI'];
if (($pos = strpos($url, '#')) !== false) $url = substr($url, 0, $pos);
// 這個 $url 必須與前端 location.href.split('#')[0] 完全一致

第十一坑：網頁授權雙模式選型（snsapi_base vs snsapi_userinfo）

建議：統一用 snsapi_userinfo，一次授權拿全量信息，避免二次跳轉。

第十二坑：H5 頁面返回需刷新，用 window.name 單標誌位解決

// 頁面載入時執行
if (window.name !== 'hasLoad') {
    location.reload(); // 首次進入/返回時強制刷新
    window.name = 'hasLoad';
} else {
    window.name = ''; // 刷新後重置，避免循環刷新
}

原理：window.name 在同標籤頁跳轉/返回時保持不變，刷新會重置。

第十三坑：微信內關閉當前 H5 頁面，回到會話列表

// 必須在 WeixinJSBridgeReady 後調用
document.addEventListener('WeixinJSBridgeReady', function() {
    WeixinJSBridge.call('closeWindow');
}, false);

適用場景：授權成功頁、支付結果頁、活動結束頁，自動關閉避免用戶手動返回。

第十四坑：別忘了引入 JSSDK 核心 JS

<script src="https://res.wx.qq.com/open/js/jweixin-1.6.0.js"></script>
// 必須在 wx.config 之前引入，建議放在 <head> 中

綜合避坑清單（建議收藏）

1. ✅ XML 回覆 To/From 互換
2. ✅ 回覆邏輯在驗證通過後
3. ✅ 菜單 URL 帶 https://
4. ✅ iOS 圖片上傳遞歸鏈式
5. ✅ 簽名 URL 去 # 且與前端一致
6. ✅ 授權優先用 snsapi_userinfo
7. ✅ access_token/jsapi_ticket 全局緩存 7000s
8. ✅ H5 返回刷新用 window.name
9. ✅ 關閉窗口用 WeixinJSBridge
10. ✅ 引入 jweixin-1.6.0.js
11. ✅ 異常日誌上報（簽名失敗、授權失敗、上傳失敗）
12. ✅ 域名配置：業務域名 + JS安全域名 + 授權域名 三合一

微信開發「坑」多源於「文檔滯後、平台差異、審核機制」。建議建立團隊內部「微信開發規範文檔」，新人必讀、老人必改，將踩坑成本降為零。