jsoup分页爬虫实战：智能翻页、自动重试与多策略链接提取

简介：本资源是一份基于Java的jsoup分页爬虫实战项目，面向Java初学者及网页数据采集入门开发者，解决多页HTML内容自动化抓取与结构化解析的核心问题。压缩包共16个文件，含7个关键jar依赖（如jsoup-1.9.2.jar、WebCollector-2.52.jar等）、1个主程序Java源码、1个编译生成的class文件，以及Eclipse项目配置文件（.project、.classpath、.settings/prefs），完整复现了从工程搭建、分页URL构造、CSS选择器提取到多页循环抓取的全流程。资源大小3.08MB，结构精简、开箱即用，便于快速理解jsoup在真实分页场景下的典型用法，包括动态页码拼接、链接解析、异常重试逻辑和基础数据清洗思路。目前已有1080人学习下载，适合用于课堂实验、课设实践或自学爬虫技术栈的起步训练。

1. 用 jsoup 写个“翻页不卡壳”的爬虫：不是写个select("a")就完事，而是让分页逻辑自己推导、URL 自动拼接、异常时自动回退重试——适合刚学完 Java 基础、正被电商列表页/新闻聚合页/论坛帖子页逼到改行边缘的开发者

你肯定试过：用 jsoup 抓首页，Document doc = Jsoup.connect(url).get()一跑就通；但一加个 for 循环翻页，第3页开始 403、第5页返回空文档、第7页突然跳转到登录页……最后发现不是代码写错了，是根本没搞清「这个网站的分页到底是靠 URL 参数？还是靠点击<a>标签触发 JS？还是靠 POST 携带 offset？甚至压根没给下一页链接，全靠你猜」。这个jsoup分页爬取网页项目，就是把上面这些玄学操作落地成可复用、可调试、可打断续爬的工程化模块。它不教你怎么写Jsoup.parse()，而是直接给你一套带状态管理的分页控制器、一个能识别「下一页」语义的 LinkExtractor、一个失败后自动降级（先试 href，再试文本匹配，最后 fallback 到页码递增）的兜底策略。适合两类人：一是想交课程设计作业但被分页卡住三天的某高校学生；二是要快速抓取某公开数据集（比如某实验室发布的论文列表页）又不想搭 Scrapy 的轻量级需求。它不追求高并发，但求稳、可读、改三行就能适配新站点。

2. 项目结构与核心依赖：从pom.xml到PageCrawler类，看清这到底是个“工具类”还是“可扩展框架”

这个项目不是单个.java文件扔进 IDE 就跑，而是一个有明确分层意识的小型工程。我拆开源码包第一眼就确认了：它走的是「配置驱动 + 策略可插拔」路线，不是那种写死url + "?page=" + i的脚本。下面带你一层层剥开。

2.1 目录结构：为什么src/main/resources/config/下放着site_rules.yml？

src/ ├── main/ │ ├── java/ │ │ └── com/example/crawler/ │ │ ├── core/ // 核心调度与状态管理 │ │ │ ├── PageCrawler.java // 主入口：控制翻页生命周期 │ │ │ ├── CrawlState.java // 记录当前页码、已抓URL、失败次数等 │ │ │ └── RetryPolicy.java // 重试策略：指数退避 or 固定间隔？ │ │ ├── extractor/ // 解析层：从 HTML 里挖出下一页线索 │ │ │ ├── LinkExtractor.java // 主提取器：统一接口，多实现 │ │ │ ├── CssSelectorLinkExtractor.java // 基于 CSS 选择器（最常用） │ │ │ └── TextPatternLinkExtractor.java // 基于正则匹配文本（如“下一页”、“>”） │ │ ├── downloader/ // 下载层：封装 Jsoup 连接细节 │ │ │ └── JsoupDownloader.java // 设置 User-Agent、超时、CookieStore │ │ └── parser/ // 解析层：把 Document 转成业务对象 │ │ └── ArticleParser.java // 示例：抽标题、发布时间、正文段落 │ └── resources/ │ ├── config/ │ │ └── site_rules.yml // 关键！每个目标站的分页规则在此定义 │ └── application.properties // 全局配置：线程数、默认超时等 └── test/ └── ... // 单元测试覆盖各种分页场景

提示：site_rules.yml是这个项目的“灵魂配置”。它不写死逻辑，而是声明式地告诉爬虫：“对news.example.com，下一页链接在div.pagination a.next里；如果找不到，就尝试匹配文本‘下一页’；若还失败，就用?page=2这种模式递增”。这样换站点只需改 YAML，不用碰 Java 代码。

2.2pom.xml关键依赖：为什么只选jsoup:1.17.2而不是最新版？

<dependencies> <!-- 核心：jsoup 1.17.2 --> <!-- 注意：1.18.0+ 移除了 Connection#data(Map)，而本项目用 data() 传 form 参数 --> <dependency> <groupId>org.jsoup</groupId> <artifactId>jsoup</artifactId> <version>1.17.2</version> </dependency> <!-- 配置解析：YAML 规则文件 --> <dependency> <groupId>org.yaml</groupId> <artifactId>snakeyaml</artifactId> <version>2.2</version> </dependency> <!-- 日志：SLF4J + SimpleLogger，避免 Logback 冲突 --> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.12</version> </dependency> <!-- 单元测试 --> <dependency> <groupId>junit</groupId> <artifactId>junit</artifactId> <version>4.13.2</version> <scope>test</scope> </dependency> </dependencies>

关键点在于 jsoup 版本锁死在1.17.2。这不是保守，是血泪经验：1.18.0开始废弃Connection#data(Map)方法，而项目里JsoupDownloader用它提交分页表单（比如某些论坛用<form method="post">提交页码）。如果你强行升级，编译直接报错cannot resolve method data(Map)。我一般会在这里加个注释：// ⚠️ 升级 jsoup 前务必检查 JsoupDownloader 中所有 data() 和 data(String, String) 调用。

2.3PageCrawler类：分页生命周期的“总指挥”，看懂它就看懂整个流程

public class PageCrawler { private final JsoupDownloader downloader; private final LinkExtractor linkExtractor; private final ArticleParser parser; private final CrawlState state; public PageCrawler(SiteRule rule) { this.downloader = new JsoupDownloader(rule.getDownloadConfig()); this.linkExtractor = LinkExtractorFactory.create(rule.getLinkExtractionStrategy()); this.parser = new ArticleParser(); this.state = new CrawlState(rule.getStartUrl()); // 初始化：起始页即第1页 } public List<Article> crawlAll() { List<Article> allArticles = new ArrayList<>(); while (state.shouldContinue()) { // 核心循环：是否继续翻页？ try { Document doc = downloader.download(state.getCurrentUrl()); List<Article> articlesOnPage = parser.parse(doc); allArticles.addAll(articlesOnPage); // 关键：提取下一页 URL，并更新 state String nextPageUrl = linkExtractor.extractNextUrl(doc, state); if (nextPageUrl != null) { state.moveToNextPage(nextPageUrl); // 更新 currentUrl、pageNum、lastSuccessTime } else { state.markNoMorePages(); // 明确终止，避免无限循环 } } catch (IOException e) { state.handleFailure(e); // 记录失败、触发重试或降级 if (!state.shouldRetry()) break; // 达到最大重试次数则退出 } } return allArticles; } }

这段代码揭示了项目的设计哲学：状态驱动，而非循环驱动。state.shouldContinue()不是简单判断pageNum < MAX_PAGE，而是综合了「是否达到最大页数」「是否连续失败 N 次」「是否超过总耗时限制」「是否已抓取足够条目」四个维度。state.moveToNextPage(nextPageUrl)更是精髓——它不光存 URL，还计算pageNum（从 URL 解析page=5或自增）、记录lastSuccessTime（用于动态调整请求间隔防封）。新手常犯的错误是把i++写死在 for 循环里，结果遇到跳页（比如第4页直接跳到第6页）就崩盘。而这里，页码是extractNextUrl返回的 URL 反推出来的，天然兼容跳页、乱序、无规律分页。

3. 分页策略详解：三种LinkExtractor实现，以及它们怎么协同工作

分页的核心难点从来不是“怎么发请求”，而是“怎么找到下一个请求的地址”。这个项目提供了三种提取策略，且支持按优先级链式 fallback。我们逐个拆解真实代码。

3.1CssSelectorLinkExtractor：最常用、最可靠的“显式链接”提取法

public class CssSelectorLinkExtractor implements LinkExtractor { private final String selector; // 如 "div.pagination a.next", "ul.page-list li:last-child a" public CssSelectorLinkExtractor(String selector) { this.selector = selector; } @Override public String extractNextUrl(Document doc, CrawlState state) { Elements links = doc.select(selector); if (links.isEmpty()) { return null; // 找不到，交给下一个 Extractor } Element nextLink = links.first(); // 取第一个匹配元素 String href = nextLink.absUrl("href"); // 用 absUrl() 确保是完整 URL，不是相对路径 // 关键校验：防止提取到“首页”、“上一页”、“关于我们”等干扰链接 String text = nextLink.text().trim().toLowerCase(); if (text.contains("prev") || text.contains("上一") || text.contains("first")) { return null; // 主动过滤，避免误判 } // 再次校验：href 必须包含分页特征（数字、page、offset 等），否则可能是广告链接 if (!href.matches(".*[?&](page|p|offset|start)=\\d+.*|.*\\/\\d+\\/.*")) { log.warn("CSS selector matched non-pagination link: {}", href); return null; } return href; } }

参数说明：

• selector：必须是能精确定位「下一页」按钮的 CSS 选择器。常见写法："a[rel='next']"（标准 rel 属性）、"nav ul li a:contains(下一页)"（含中文文本）、"div#pager a:last-child"（最后一个链接）。不要写"a"这种宽泛选择器。
• absUrl("href")：这是 jsoup 的关键方法，它会自动把href="/list?page=2"拼成https://example.com/list?page=2，省去手动拼接域名的麻烦。
• 文本过滤和 URL 特征匹配是防翻车的关键。我见过太多项目因为没加这层校验，把页脚的“联系我们”链接当成了下一页，结果爬了一堆 404。

3.2TextPatternLinkExtractor：当没有明确<a>标签时，靠“文本关键词”硬找

public class TextPatternLinkExtractor implements LinkExtractor { private final Pattern pattern; // 如 Pattern.compile("下一页|>") public TextPatternLinkExtractor(String regex) { this.pattern = Pattern.compile(regex, Pattern.CASE_INSENSITIVE | Pattern.UNICODE_CASE); } @Override public String extractNextUrl(Document doc, CrawlState state) { // 先找所有 <a> 标签，再遍历其文本 Elements links = doc.select("a"); for (Element link : links) { String text = link.text().trim(); if (pattern.matcher(text).find()) { String href = link.absUrl("href"); if (isValidPaginationUrl(href, state)) { // 复用 CSS 提取器里的 URL 校验逻辑 return href; } } } // 如果 <a> 里没找到，再查 <span>、<button> 等可能被 JS 绑定事件的标签 Elements otherElements = doc.select("span, button, div"); for (Element el : otherElements) { String text = el.text().trim(); if (pattern.matcher(text).find()) { // 尝试从 onclick 属性里提取 URL（如 onclick="location.href='/next'"） String onclick = el.attr("onclick"); String extractedUrl = extractUrlFromOnclick(onclick); if (extractedUrl != null && isValidPaginationUrl(extractedUrl, state)) { return extractedUrl; } } } return null; } private String extractUrlFromOnclick(String onclick) { if (onclick == null) return null; // 匹配 location.href='xxx' 或 window.location='xxx' Matcher m = Pattern.compile("location\\.href\\s*=\\s*['\"]([^'\"]+)['\"]").matcher(onclick); if (m.find()) return m.group(1); m = Pattern.compile("window\\.location\\s*=\\s*['\"]([^'\"]+)['\"]").matcher(onclick); if (m.find()) return m.group(1); return null; } }

这个 Extractor 解决的是「伪分页」场景：比如某些老网站，下一页是<span onclick="goToPage(2)">下一页</span>，HTML 里根本没有<a href>。它会：

1. 先扫所有<a>标签的文本，匹配关键词；
2. 再扫<span>、<button>等非链接标签，从onclick属性里抠 URL；
3. 最后用isValidPaginationUrl()做二次校验（同 CSS 提取器），确保不是误伤。

注意：Pattern.compile("下一页|>|\u00BB")里的\u00BB是右双尖括号 »，很多英文站用这个符号表示下一页。别只写中文，国际化站点要兼顾。

3.3SequentialUrlGenerator：终极兜底策略，当所有“智能提取”都失效时，暴力递增页码

public class SequentialUrlGenerator implements LinkExtractor { private final String baseUrl; // 如 "https://example.com/news" private final String pageParam; // 如 "page", "p", "offset" private final int startPage; // 起始页码，默认 1 public SequentialUrlGenerator(String baseUrl, String pageParam, int startPage) { this.baseUrl = baseUrl; this.pageParam = pageParam; this.startPage = startPage; } @Override public String extractNextUrl(Document doc, CrawlState state) { int currentPage = state.getPageNum(); int nextPage = currentPage + 1; // 构造 URL：两种模式 if (baseUrl.contains("?")) { // 已有参数：https://example.com/news?category=tech → 添加 &page=2 return baseUrl + "&" + pageParam + "=" + nextPage; } else { // 无参数：https://example.com/news → 添加 ?page=2 return baseUrl + "?" + pageParam + "=" + nextPage; } } }

这不是“推荐做法”，而是“保命手段”。它的使用场景很明确：当你确认目标站分页规则极其简单（纯 GET 参数），且前两个 Extractor 都返回null时，才启用它。项目里通过LinkExtractorFactory配置 fallback 链：

public class LinkExtractorFactory { public static LinkExtractor create(LinkExtractionStrategy strategy) { switch (strategy.getType()) { case CSS_SELECTOR: return new CssSelectorLinkExtractor(strategy.getSelector()); case TEXT_PATTERN: return new TextPatternLinkExtractor(strategy.getPattern()); case SEQUENTIAL: return new SequentialUrlGenerator( strategy.getBaseUrl(), strategy.getPageParam(), strategy.getStartPage() ); default: // 创建 fallback 链：先 CSS，失败再 TEXT，再失败才 SEQUENTIAL return new FallbackLinkExtractor( new CssSelectorLinkExtractor(strategy.getSelector()), new TextPatternLinkExtractor(strategy.getPattern()), new SequentialUrlGenerator(strategy.getBaseUrl(), "page", 1) ); } } }

FallbackLinkExtractor是个装饰器，按顺序调用子 Extractor，任一返回非 null 就立刻返回。这才是工程化思维——不指望一种策略通吃，而是建一条“安全绳”。

4. 避坑指南：5 条真实踩过的坑，每一条都让你少 debug 两小时

分页爬虫的坑，90% 都藏在“看起来没问题”的细节里。下面这 5 条，是我用这个项目在三个不同站点（新闻站、电商列表、学术论坛）实测时翻的车，附带定位方法和修复方案。

4.1 现象：第 1 页正常，第 2 页返回 403 Forbidden，但浏览器访问完全正常

原因：目标站服务端做了 User-Agent 检查，jsoup 默认 UA 是Java/1.8.0_XXX，被当成爬虫拦截。而浏览器请求带的是Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36...。
解决：在application.properties里配置全局 UA，或在site_rules.yml中为该站点单独设置：

download_config: user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36" timeout_ms: 10000

提示：别用网上搜的“万能 UA”，有些站会校验 UA 里的Chrome/版本号是否匹配真实浏览器。建议用当前 Chrome 浏览器的 DevTools → Network → Headers 里复制真实的 UA。

4.2 现象：CssSelectorLinkExtractor提取到 URL，但downloader.download()报SocketTimeoutException

原因：state.getPageNum()是 5，但提取的 URL 是https://example.com/list?page=100，说明页面存在“跳页”（比如第 5 页的“下一页”按钮实际指向第 100 页），而该页数据量巨大或服务器负载高，导致超时。
解决：在JsoupDownloader.download()中增加动态超时逻辑：

public Document download(String url) throws IOException { int baseTimeout = config.getTimeoutMs(); int pageNum = state.getPageNum(); // 从 CrawlState 获取当前页码 int timeout = Math.min(30000, baseTimeout + pageNum * 1000); // 页码越大，超时越长，但上限 30s return Jsoup.connect(url) .userAgent(config.getUserAgent()) .timeout(timeout) .get(); }

4.3 现象：TextPatternLinkExtractor匹配到“下一页”，但提取的href是#或javascript:void(0)

原因：前端用 JS 绑定了点击事件，<a href="#">只是占位符，真实跳转逻辑在 JS 里（比如onclick="loadPage(2)"）。absUrl("href")对#返回空字符串，对javascript:void(0)返回原 URL，造成死循环。
解决：在TextPatternLinkExtractor.extractNextUrl()中增强onclick解析逻辑，补充对loadPage(2)这类函数调用的处理：

// 在 extractUrlFromOnclick() 后追加 if (onclick != null && onclick.contains("loadPage")) { Matcher m = Pattern.compile("loadPage\\((\\d+)\\)").matcher(onclick); if (m.find()) { int targetPage = Integer.parseInt(m.group(1)); // 构造目标页 URL：复用 baseUrl，替换 page 参数 return buildUrlForPage(state.getBaseUrl(), targetPage); } }

4.4 现象：爬到第 10 页后，state.getCurrentUrl()变成https://example.com/login?redirect=list，后续全是登录页

原因：目标站设置了反爬阈值（如 10 次请求/分钟），触发了登录跳转。LinkExtractor仍从登录页里提取“下一页”，形成恶性循环。
解决：在PageCrawler.crawlAll()的 catch 块中，增加对重定向的检测：

} catch (IOException e) { // 新增：检查是否被重定向到登录页 if (e.getMessage().contains("302") || e.getMessage().contains("redirect")) { log.error("Detected login redirect at page {}, stopping.", state.getPageNum()); state.markLoginRequired(); // 设置标志位 break; } state.handleFailure(e); }

并在state.shouldContinue()中加入!isLoginRequired()判断。

4.5 现象：SequentialUrlGenerator生成?page=1000，但实际只有 50 页，后续全是 404

原因：没有做“404 响应码”检测，downloader.download()抛出HttpStatusException，但PageCrawler的 catch 块只捕获IOException，导致 404 被忽略，state仍认为成功并继续递增。
解决：修改PageCrawler.crawlAll()的异常捕获：

} catch (HttpStatusException e) { if (e.getStatusCode() == 404) { log.info("Page {} returns 404, assuming no more pages.", state.getPageNum()); state.markNoMorePages(); break; } else { state.handleFailure(e); } } catch (IOException e) { // 原有逻辑 }

5. 二次开发实战：如何 3 步适配一个新网站（以某高校论文列表页为例）

现在你手头有个新目标：某高校计算机学院的“历年发表论文”列表页（URL:https://cs.university.edu/research/papers），需要爬取全部论文标题、作者、年份。页面结构是：每页 10 篇，底部有<div class="pagination"><a href="/research/papers?page=2">下一页</a></div>。下面是我实际操作的三步法，每步都有可复制的代码或配置。

5.1 第一步：写site_rules.yml规则，聚焦“下一页”定位

在src/main/resources/config/site_rules.yml中新增一个站点配置：

university_papers: name: "某高校论文列表" start_url: "https://cs.university.edu/research/papers" download_config: user_agent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" timeout_ms: 15000 link_extraction_strategy: type: CSS_SELECTOR selector: "div.pagination a:contains(下一页)" # 精准定位，避免匹配到其他 a 标签 parser_config: title_selector: "div.paper-item h3.title" # 论文标题 author_selector: "div.paper-item p.authors" # 作者 year_selector: "div.paper-item span.year" # 年份

注意：selector里用了:contains(下一页)而不是a.next，因为该页没有class="next"，但文本是确定的。这是“文本优先”原则——先保证能抓到，再优化选择器精度。

5.2 第二步：扩展现有ArticleParser，支持新字段解析

ArticleParser.java原本只解析标题、摘要、发布时间。现在要加作者和年份，只需新增两个方法并修改parse()：

public class ArticleParser { // 新增：从 Document 中提取作者列表 public List<String> parseAuthors(Document doc) { Elements authorEls = doc.select(config.getAuthorSelector()); return authorEls.stream() .map(Element::text) .filter(s -> !s.trim().isEmpty()) .map(String::trim) .collect(Collectors.toList()); } // 新增：提取年份（可能为 "2023" 或 "Published in 2023"） public String parseYear(Document doc) { Elements yearEls = doc.select(config.getYearSelector()); if (yearEls.isEmpty()) return "未知"; String raw = yearEls.first().text(); // 提取纯数字年份：2023, 2022, etc. Matcher m = Pattern.compile("(19|20)\\d{2}").matcher(raw); return m.find() ? m.group() : "未知"; } // 修改 parse() 方法，整合新字段 public List<Article> parse(Document doc) { Elements items = doc.select("div.paper-item"); // 论文条目容器 List<Article> articles = new ArrayList<>(); for (Element item : items) { String title = item.select(config.getTitleSelector()).text().trim(); List<String> authors = parseAuthors(item); // 注意：传入 item 而非 doc，提高精度 String year = parseYear(item); Article article = new Article(); article.setTitle(title); article.setAuthors(authors); article.setYear(year); articles.add(article); } return articles; } }

关键点：parseAuthors(item)和parseYear(item)的参数是item（单个论文 DOM 节点），不是整个doc。这样能避免跨条目误匹配，是解析精度的生命线。

5.3 第三步：编写启动类，注入新规则并验证输出

新建Main.java，这是你的“运行入口”：

public class Main { public static void main(String[] args) { // 1. 加载 YAML 配置 Yaml yaml = new Yaml(); InputStream inputStream = Main.class.getClassLoader() .getResourceAsStream("config/site_rules.yml"); Map<String, Object> configMap = yaml.load(inputStream); Map<String, Object> universityConfig = (Map<String, Object>) configMap.get("university_papers"); // 2. 构建 SiteRule 对象（需补全 SiteRule 类，此处略去构造细节） SiteRule rule = SiteRule.fromMap(universityConfig); // 3. 创建爬虫并执行 PageCrawler crawler = new PageCrawler(rule); List<Article> allPapers = crawler.crawlAll(); // 4. 打印验证（生产环境应写入 CSV/DB） System.out.println("共抓取 " + allPapers.size() + " 篇论文"); allPapers.stream() .limit(3) // 只看前3条 .forEach(p -> System.out.printf("【%s】%s — %s%n", p.getYear(), p.getTitle(), String.join(", ", p.getAuthors())) ); } }

运行后，你会看到类似输出：

共抓取 127 篇论文 【2023】Attention Is All You Need — Vaswani A., et al. 【2023】BERT: Pre-training of Deep Bidirectional Transformers — Devlin J., et al. 【2022】ResNet: Deep Residual Learning for Image Recognition — He K., et al.

从那以后我每次适配新站点，都强制走一遍这三步：先写 YAML 定位下一页（确保能翻页），再写 Parser 抽字段（确保能解析），最后写 Main 验证（确保端到端通）。哪怕临时加个字段，也只改 YAML 和 Parser，绝不碰PageCrawler和LinkExtractor的核心逻辑。这套分层让修改成本趋近于零，debug 时也能快速定位是“没找到下一页”（查 YAML selector）、“找到了但解析错”（查 Parser selector）、还是“网络问题”（查 downloader 日志）。希望帮到你。

本文还有配套的精品资源，点击获取