解決 Java 網路程式 IPv6 兼容性問題：一鍵配置強制使用 IPv4 棧

問題背景

在使用 JGroups、MantaRay 等分散式通訊框架時，常遭遇 IPv6 導致的連線失敗、綁定異常等問題。傳統做法是作業系統層面停用 IPv6 協議，但這屬於「蹩腳方案」，影響面廣且難以維運。Java 提供標準系統屬性即可優雅解決。

核心解決方案

啟動 JVM 時加入以下系統屬性：

-Djava.net.preferIPv4Stack=true

配置方式

• 命令列直接啟動：java -Djava.net.preferIPv4Stack=true -jar app.jar
• 腳本/服務配置：在啟動腳本 JAVA_OPTS 或 CATALINA_OPTS（Tomcat）中添加。
• IDE 開發環境：Run Configuration → VM Arguments 添加。
• 容器化部署：Dockerfile ENV JAVA_OPTS="-Djava.net.preferIPv4Stack=true" 或 docker-compose environment 變數。

官方文檔原理說明

java.net.preferIPv4Stack (default: false)
若作業系統支援 IPv6，底層原生 Socket 預設為 IPv6 Socket，允許 Java 應用同時連接/接受 IPv4 與 IPv6 主機。
若應用僅需使用 IPv4 Socket，設定此屬性為 true 即可強制使用 IPv4 棧。

適用場景與驗證

進階補充

• 若需精細控制，可搭配 -Djava.net.preferIPv4Addresses=true（優先使用 IPv4 位址，但仍保留 IPv6 棧）。
• Java 11+ 可透過 java.net.NetUtils 程式化控制，但啟動參數仍為最通用做法。
• 雲原生環境建議：容器網路預設 IPv4，直接加入此參數規避未知相容性風險。

總結

一行啟動參數解決 Java 網路程式 IPv6 兼容性難題，無需修改代碼、無需調整作業系統設定，是分散式系統、微服務、中介軟體開發的必備運維知識。