Jsoup 連線逾時異常處理：設定 timeout 參數完整指南

解決 java.net.SocketTimeoutException: Read timed out

使用 Jsoup 爬取網頁時，預設連線逾時極短（約 3 秒），對回應緩慢的網站易拋出 SocketTimeoutException。透過 timeout(毫秒) 方法即可調整。

快速解決方案

// 設定 5 秒逾時（連線 + 讀取）
Document doc = Jsoup.connect("https://example.com").timeout(5000).get();

完整對比測試代碼

未設定 timeout（易發生逾時）

package jsoupTest;

import java.io.IOException;
import org.jsoup.*;
import org.jsoup.nodes.Document;

public class JsoupTest {
    public static void main(String[] args) throws IOException {
        String url = "https://www.jb51.net";
        long start = System.currentTimeMillis();
        Document doc = null;
        try {
            doc = Jsoup.connect(url).get(); // 無 timeout 設定
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            System.out.println("耗時：" + (System.currentTimeMillis() - start) + "ms");
        }
        if (doc != null) {
            System.out.println("Title: " + doc.title());
        }
    }
}

可能輸出：

java.net.SocketTimeoutException: Read timed out
    at java.net.SocketInputStream.socketRead0(Native Method)
    ...
耗時：3885ms
Exception in thread "main" java.lang.NullPointerException

設定 timeout(5000) 後穩定成功

package jsoupTest;

import java.io.IOException;
import org.jsoup.*;
import org.jsoup.nodes.Document;

public class JsoupTest {
    public static void main(String[] args) throws IOException {
        String url = "https://www.jb51.net";
        long start = System.currentTimeMillis();
        Document doc = null;
        try {
            doc = Jsoup.connect(url).timeout(5000).get(); // 5 秒逾時
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            System.out.println("耗時：" + (System.currentTimeMillis() - start) + "ms");
        }
        if (doc != null) {
            System.out.println("Title: " + doc.title());
        }
    }
}

進階連線參數配置

Document doc = Jsoup.connect(url)
    .timeout(10000)           // 連線與讀取總逾時 10 秒
    .userAgent("Mozilla/5.0") // 設定 User-Agent
    .referrer("https://google.com")
    .header("Accept", "text/html")
    .cookie("session", "id")
    .followRedirects(true)
    .maxBodySize(0)           // 0 表示不限制回應大小
    .get();

常見逾時相關異常

最佳實踐建議

• 預設設定 timeout(10000) 以上，視目標站點回應速度調整。
• 搭配 .ignoreHttpErrors(true) 讓 4xx/5xx 狀態碼不拋出異常，由業務邏輯判斷。
• 生產環境建議使用 HttpClient 或 OkHttp 作為底層連線管理器，Jsoup 僅負責解析。