微信公眾平台 Java 開發 URL 配置失敗：內網穿透（NAT/花生殼/Ngrok）與 Token 驗證完整排查指南

常見失敗現象

• 提交配置提示：「URL 超時」、「Token 驗證失敗」、「服務器不可用」。
• 本地測試 `curl -X GET "https://localhost:8080/wechat?signature=...&echostr=123"` 正常，但公網不可達。

核心前提：微信服務器**必須能直接訪問你的公網 HTTPS URL**

• 協議：**HTTPS**（強制，HTTP 會被拒絕）。
• 端口：**443**（標準端口，不可自定義）。
• 域名：**已備案域名**（中國大陸主體），且綁定有效 SSL 證書。
• 路徑：任意（如 `/wechat`），需與 Controller mapping 一致。

本地開發環境接入公網三大方案

Ngrok 快速上手（推薦新手）

1. 註冊 ngrok.com 獲取 Authtoken。
2. 下載對應系統客戶端，解壓：./ngrok authtoken YOUR_TOKEN。
3. 啟動隧道指向本地 Tomcat 端口（默認 8080）：
   ./ngrok http 8080
4. 複製輸出的 **HTTPS Forwarding URL**（如 `https://abc123.ngrok.io`）。
5. 微信公眾平台配置：
   URL: `https://abc123.ngrok.io/wechat` (你的 Controller 路徑)
   Token: 自定義字符串（需與代碼一致）

Token 驗證邏輯（Java 代碼）

@GetMapping("/wechat")
public void verify(HttpServletRequest req, HttpServletResponse resp) throws IOException {
    String signature = req.getParameter("signature");
    String timestamp = req.getParameter("timestamp");
    String nonce = req.getParameter("nonce");
    String echostr = req.getParameter("echostr");

    String token = "YOUR_TOKEN"; // 與公眾平台配置一致
    String[] arr = {token, timestamp, nonce};
    Arrays.sort(arr);
    String sortedStr = String.join("", arr);
    String sha1 = DigestUtils.sha1Hex(sortedStr); // Apache Commons Codec

    if (sha1.equals(signature)) {
        resp.getWriter().write(echostr); // **原樣返回 echostr，不要加任何字符/換行**
    } else {
        resp.getWriter().write("fail");
    }
}

避坑清單

• echostr 必須原樣返回：任何 `System.out.println`、日誌、多餘空格、JSON 包裹都會導致驗證失敗。
• HTTPS 證書必須受信：自簽證書、過期證書、域名不匹配會導致微信服務器拒絕握手（URL 超時）。Ngrok/云服務器自動提供受信證書。
• 防火牆/安全組放行 443/80：云服務器安全組、本地 Windows 防火牆、路由器防火牆。
• Controller 路徑精確匹配：微信發送 GET 請求到配置的完整 URL，Spring Boot `@GetMapping("/wechat")` 需與 URL 路徑一致。
• 開發模式 vs 生產模式：開發用 Ngrok/FRP，生產**必須**遷移到備案域名+云服務器，Ngrok 免費版不穩定不可用於生產。

「公網 HTTPS + 域名備案 + Token 邏輯正確 + echostr 原樣返回」四要素缺一不可，逐項核對即可解決 99% 接入失敗。