# 在线搜索错误修复 与 书→目录→章节 导航流程 — 完整解决方案 > 分析日期:2026-06-21 > 参考项目:[legado-with-MD3](https://github.com/HapeLee/legado-with-MD3) > 涉及范围:Sakura Mobile (Flutter) > 说明:本文档提供完整的问题分析与解决方案设计,不包含实际代码改动。 --- ## 目录 1. [总体结论](#一总体结论) 2. [问题诊断](#二问题诊断) 3. [P0:必须优先修改](#三p0必须优先修改) 4. [P1:第二阶段修改](#四p1第二阶段修改) 5. [P2:后续增强](#五p2后续增强) 6. [优先级总表](#六优先级总表) 7. [页面与数据流设计](#七页面与数据流设计) 8. [数据模型扩展](#八数据模型扩展) 9. [Legado 书源规则字段对照](#九legado-书源规则字段对照) 10. [附录:关键文件清单](#十附录关键文件清单) --- ## 一、总体结论 **不要只修 UI,也不要只做错误提示兜底。** 真正应该改成的完整流程是: ``` 搜索页 (ExplorePage) ↓ 在线书籍详情页 (OnlineBookDetailPage) ← 合并 BookInfo + TOC 的 UI ├─ 书籍信息(封面、书名、作者、来源、简介) ├─ 章节列表(内嵌加载,不跳独立 TOC 页) │ ├─ 分页加载 │ └─ 正序/倒序切换 └─ 快捷操作:「从第一章开始阅读」「保存到书架」 ↓ 阅读器 (OnlineMangaReaderPage / OnlineNovelReaderPage) ├─ 章节驱动(非 URL 驱动) ├─ 上一章 / 下一章 导航 ├─ 下一章预加载 └─ 阅读记录 ``` 核心理念: ``` 页面合并,解析分层; 缓存前置,持久化后置; 目录回退要识别章节,不要盲扫链接; 阅读器必须从 URL 驱动改成章节驱动。 ``` --- ## 二、问题诊断 ### 2.1 问题一:搜索结果显示 `unknown:none` #### 现象 用户在 APP 在线搜索漫画/小说时,搜索结果中某些条目显示为 `unknown:none`。 #### 根因 **位置**:`sakura_mobile/lib/src/core/legado_engine.dart:563-569` ```dart var message = error .toString() .replaceFirst(RegExp(r'^(Exception|StateError):\s*'), ''); if (message.trim() == '[unknown]: null' || message.trim() == 'null') { message = 'Target site returned an empty or invalid response.'; } ``` 当前只匹配了 `[unknown]: null` 和 `null`,但 Dio 在不同平台、不同错误类型下会抛出多种格式的底层异常消息: | 平台/场景 | 可能的错误消息 | 是否处理 | |-----------|---------------|----------| | Android | `[unknown]: null` | ✅ 已匹配 | | Android | `[unknown]: none` | ❌ **漏掉,原样展示** | | iOS | `Connection failed: unknown:none` | ❌ 漏掉 | | Windows 桌面 | `DioException [unknown]: null` | ❌ 部分匹配失败 | | 超时 | `Connection timed out` | ❌ 漏掉 | | DNS 失败 | `No address associated with hostname` | ❌ 漏掉 | | 编码错误 | `FormatException: Bad UTF-8 encoding` | ❌ 走 FormatException 分支,不友好 | 这些未处理的错误消息被原样透传到 `SearchItem.errorMessage`,最终在 UI 的 subtitle 中展示为 `源名称 - unknown:none`。 #### 搜索结果字段提取失败的连锁反应 **位置**:`legado_engine.dart:60-98` 当书源的解析规则与目标网站 HTML 结构不匹配时: - `title` 为空 → 该结果被 `.where()` 过滤掉 → 整个源的搜索结果为空 - `author` 为空 → subtitle 中显示为 null - `detailUrl` 为空 → 点击后 URL 为空 → 报错 --- ### 2.2 问题二:缺少「书→目录→章节」导航流程 #### 现象 用户搜索到一本书后,点击结果**直接进入阅读器**,而不是进入书籍详情页。结果是: 1. 阅读器把书籍详情页 HTML 当正文展示 → 乱码/空白/无关图片 2. 用户看不到章节列表,无法选择具体章节阅读 #### 根因一:数据模型缺少三个关键规则模块 **位置**:`sakura_mobile/lib/src/core/legado_models.dart:21-86` 当前 `LegadoSource` 只包含搜索相关的规则字段: ``` searchUrl, searchListRule, searchNameRule, searchAuthorRule, searchCoverRule, searchDetailRule, searchMethod, searchBody ``` 完全缺失 Legado 标准书源中的三个关键规则模块: | 模块 | 作用 | 关键字段 | |------|------|---------| | `ruleBookInfo` | 解析书籍详情页 → 得到元数据 + 目录 URL | name, author, cover, intro, **tocUrl** | | `ruleToc` | 解析目录页 → 得到章节列表 | chapterList, chapterName, chapterUrl | | `ruleContent` | 解析章节页 → 得到正文/图片 | content, nextChapterUrl, prevChapterUrl | 这三个模块是 Legado 生态的标准配置,被数千个书源规则所遵循。当前项目只实现了其中的搜索模块。 #### 根因二:搜索结果点击逻辑错误 **位置**:`sakura_mobile/lib/src/pages/explore_page.dart:174-228` (`_openItem` 方法) ```dart // 在线结果 → 直接打开阅读器(❌ 错误!) if (mode == UnifiedSearchMode.manga) { Navigator.of(context).push(MaterialPageRoute( builder: (_) => OnlineMangaReaderPage( source: source, title: item.title, detailUrl: item.detailUrl ?? item.coverUrl ?? '', // ← 书籍详情页 URL! ), )); } ``` `detailUrl` 在 Legado 规则中的语义是**书籍详情页 URL**,不是章节内容 URL。这个 URL 指向的页面包含封面、书名、作者、简介、章节目录链接——唯独没有章节正文。 将此 URL 直接传入阅读器,阅读器会: - 漫画:调用 `fetchImageUrls()` → 提取详情页所有 `` → 返回封面 + 广告图 + 导航图标 - 小说:调用 `fetchPlainText()` → 提取详情页纯文本 → 返回简介混合着页面导航文字 #### 根因三:阅读器缺少章节概念 两个在线阅读器都接收单一的 `detailUrl` 参数,没有: - 章节列表 - 上一章/下一章导航 - 阅读进度记录 --- ## 三、P0:必须优先修改 > 这些是当前问题的直接根因,需要最先实施。 ### 1. 修复 `unknown:none` 错误展示 **修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` → `_shortError()` 方法 **目标**:将所有 Dio 底层异常消息逐一映射为用户可读的中文提示,不再有原始异常消息泄漏到 UI。 **错误消息映射表**: ``` [unknown]: null → 目标站点返回了空响应,请检查书源是否仍然有效 [unknown]: none → 目标站点连接失败,请检查网络或更换书源 unknown:none → 连接异常,书源可能已失效 Connection refused → 目标站点拒绝了连接,可能需要 Cookie 或反爬处理 Connection timed out → 连接超时,请稍后重试 No address associated → 无法解析目标站点域名,请检查网络 Bad UTF-8 encoding → 响应编码异常,请检查书源的 charset 配置 null → 目标站点返回了无效响应 ``` **实现思路**: ```dart String _shortError(Object error) { // 1. Dio 网络异常 — 按错误类型精准映射 if (error is DioException) { final host = error.requestOptions.uri.host; final target = host.isEmpty ? '目标站点' : host; switch (error.type) { case DioExceptionType.connectionTimeout: case DioExceptionType.receiveTimeout: case DioExceptionType.sendTimeout: return '连接 $target 超时,请稍后重试。'; case DioExceptionType.connectionError: return '无法连接 $target,请检查网络或更换书源。'; case DioExceptionType.badResponse: final code = error.response?.statusCode ?? 0; if (code == 404) return '书源搜索接口已失效(404)。'; if (code == 403 || code == 444) return '$target 拒绝了访问,可能需要 Cookie 配置。'; return '$target 返回了异常状态(HTTP $code)。'; default: break; } } // 2. FormatException — 编码/格式问题 if (error is FormatException) { final msg = error.message.toLowerCase(); if (msg.contains('utf') || msg.contains('encoding')) return '响应编码异常,请检查书源的 charset 配置。'; return '书源规则期望 JSON 格式,但站点返回了其他内容。'; } // 3. 原始消息归一化 — 兜底处理所有未分类的异常文本 var message = error .toString() .replaceFirst(RegExp(r'^(Exception|StateError|DioException):\s*'), ''); final trimmed = message.trim(); // 按精确度从高到低匹配 if (trimmed == '[unknown]: null' || trimmed == 'null') return '目标站点返回了空响应,请检查书源是否仍然有效。'; if (trimmed == '[unknown]: none' || trimmed == 'unknown:none') return '连接异常,书源可能已失效。'; if (trimmed.toLowerCase().contains('connection refused')) return '目标站点拒绝了连接。'; if (trimmed.toLowerCase().contains('connection timed out')) return '连接超时,请稍后重试。'; if (trimmed.toLowerCase().contains('no address associated')) return '无法解析目标站点域名,请检查网络。'; // 4. 兜底截断,避免超长异常堆栈泄漏到 UI if (message.length > 120) message = '${message.substring(0, 120)}...'; return message.isEmpty ? '未知错误' : message; } ``` **同时修改 UI 层**(`explore_page.dart::_SearchResultTile`): - 当 `item.author` 为空时显示"未知作者"而非空白 - 当 `item.isError` 时,subtitle 中的错误消息不应再包含原始异常类名 --- ### 2. 扩展 `LegadoSource` 数据模型 **修改位置**:`sakura_mobile/lib/src/core/legado_models.dart` 当前模型只支持搜索规则。需要新增三个规则模块的字段。 **新增字段**: ```dart class LegadoSource { // ===== 现有字段(保持不变)===== final String id; final String name; final String url; final int type; // 0=小说, 2=漫画 final bool enabled; final String? userAgent; final Map headers; // ... 现有搜索规则字段 ... // ===== 🆕 BookInfo 规则(从 ruleBookInfo 解析)===== final String? bookInfoUrl; // 详情页 URL 模板(可选,默认用搜索结果的 detailUrl) final String? bookInfoNameRule; // 提取书名(CSS 选择器) final String? bookInfoAuthorRule; // 提取作者 final String? bookInfoCoverRule; // 提取封面 final String? bookInfoIntroRule; // 提取简介 final String? bookInfoTocRule; // 提取目录页 URL ⭐ 最关键字段 // ===== 🆕 TOC 规则(从 ruleToc 解析)===== final String? tocUrl; // 目录页 URL 模板(可选,支持 {{page}}) final String? tocListRule; // 提取章节条目列表 final String? tocNameRule; // 提取章节名称 final String? tocUrlRule; // 提取章节链接 final String? tocNextPageRule; // 提取下一页目录的 URL(用于分页) // ===== 🆕 Content 规则(从 ruleContent 解析)===== final String? contentRule; // 提取正文/图片内容 final String? contentNextRule; // 提取下一章链接 final String? contentPrevRule; // 提取上一章链接 } ``` **`fromJson()` 中新增的解析逻辑**: ```dart // 从 ruleBookInfo 提取 final bookInfo = _map(json['ruleBookInfo']); bookInfoNameRule = _firstString([ bookInfo['name'], bookInfo['bookName'], ]); bookInfoAuthorRule = _firstString([ bookInfo['author'], bookInfo['bookAuthor'], ]); bookInfoCoverRule = _firstString([ bookInfo['coverUrl'], bookInfo['cover'], ]); bookInfoIntroRule = _firstString([ bookInfo['intro'], bookInfo['introduce'], bookInfo['desc'], ]); bookInfoTocRule = _firstString([ bookInfo['tocUrl'], bookInfo['chapterUrl'], bookInfo['catalogUrl'], bookInfo['directoryUrl'], ]); // 从 ruleToc 提取 final toc = _map(json['ruleToc']); tocListRule = _firstString([ toc['chapterList'], toc['chapters'], toc['list'], ]); tocNameRule = _firstString([ toc['chapterName'], toc['name'], toc['title'], ]); tocUrlRule = _firstString([ toc['chapterUrl'], toc['url'], toc['href'], ]); tocNextPageRule = _firstString([ toc['nextTocUrl'], toc['nextPage'], toc['nextPageUrl'], ]); // 从 ruleContent 提取 final content = _map(json['ruleContent']); contentRule = _firstString([ content['content'], content['text'], content['body'], ]); contentNextRule = _firstString([ content['nextChapterUrl'], content['next'], content['nextPage'], ]); contentPrevRule = _firstString([ content['prevChapterUrl'], content['prev'], content['prevPage'], ]); ``` **`copyWith` 也需要同步扩展**,确保 `setEnabled()` 等现有方法能正常工作。 --- ### 3. 新增在线书籍详情页(合并 BookInfo + TOC UI) **新增文件**:`sakura_mobile/lib/src/pages/online_book_detail_page.dart` **关键设计决策**:不要创建独立的 `OnlineTocPage`。将 BookInfo 和章节列表放在**同一个页面**中,但数据加载保持**两次独立请求**(因为很多书源的 `detailUrl ≠ tocUrl`)。 ``` ┌──────────────────────────────────────┐ │ ← 返回 书籍详情 📤 │ AppBar ├──────────────────────────────────────┤ │ │ │ ┌──────────────┐ │ │ │ │ │ 封面图 │ │ 书籍封面 │ │ (CachedNetworkImage) │ │ │ │ │ └──────────────┘ │ │ │ │ 斗罗大陆 │ 书名(大标题) │ 唐家三少 · 笔趣阁 · 连载中 │ 作者/来源/状态 一行 │ │ │ ┌──────────────────────────────┐ │ │ │ 简介 │ 简介卡片 │ │ 唐门外门弟子唐三,因偷学内门 │ (可展开/收起) │ └──────────────────────────────┘ │ │ │ │ ┌──────────────────────────────┐ │ │ │ ▶ 从第一章开始阅读 │ 快捷操作按钮 │ └──────────────────────────────┘ │ │ ┌──────────────────────────────┐ │ │ │ 💾 保存到书架 │ 保存操作 │ └──────────────────────────────┘ │ │ │ │ ──────── 章节目录 (共 336 章) ───── │ 分隔标题 │ [正序 ↑] [倒序 ↓] │ 排序切换 │ │ │ ┌──────────────────────────────────┐│ │ │ 📖 第一章 楔子 ││ 章节条目 │ └──────────────────────────────────┘│ │ ┌──────────────────────────────────┐│ │ │ 📖 第二章 唐三的武魂 ││ │ └──────────────────────────────────┘│ │ ┌──────────────────────────────────┐│ │ │ 📖 第三章 修炼之路 ││ │ └──────────────────────────────────┘│ │ ┌──────────────────────────────────┐│ │ │ ... 更多章节(滚动加载) ││ 支持无限滚动 │ │ 正在加载第2页... ││ TOC 分页指示器 │ └──────────────────────────────────┘│ │ │ └──────────────────────────────────────┘ ``` **数据加载方式(分段异步)**: ``` 第一步:请求 BookInfo(用 bookInfoRule 解析 detailUrl) → 拿到 title, author, cover, intro, tocUrl → 立即渲染页面上半部分(封面+书名+作者+简介+快捷按钮) → 章节列表区域显示骨架屏 loading 第二步:请求 TOC(用 chapterListRule 解析 tocUrl) → 拿到 List → 章节列表区域从骨架屏切换为真实数据 → 如果有 tocNextPageRule,继续加载后续页 两步之间不互相阻塞:BookInfo 失败 → 整个页面显示错误;TOC 失败 → 上半部分正常展示,下半部分显示"目录加载失败,点击重试" ``` **重要**: ``` 合并页面 ≠ 合并请求 因为很多书源: detailUrl (书籍详情页) ≠ tocUrl (章节目录页,可能是独立的分页 URL) 详情和目录必须允许两次独立的 HTTP 请求。 ``` --- ### 4. 修改搜索结果点击逻辑 **修改位置**:`sakura_mobile/lib/src/pages/explore_page.dart` → `_openItem()` 方法 **当前逻辑(错误)**: ``` 点击在线结果 → 直接打开 OnlineMangaReaderPage / OnlineNovelReaderPage (把 detailUrl 当成章节内容 URL 传给阅读器) ``` **改为**: ``` 点击在线结果 → 打开 OnlineBookDetailPage(detailUrl) → 用户在详情页看到书籍信息 + 章节列表 → 点击某个章节 → 打开阅读器(传入章节 URL) → 或点击「从第一章开始阅读」→ 自动打开第一个章节 ``` ```dart void _openItem(SearchItem item) { // 云库结果(不变) if (item.artwork != null) { Navigator.of(context).push( MaterialPageRoute(builder: (_) => ArtworkDetailPage(artwork: item.artwork!)), ); return; } if (item.novel != null) { Navigator.of(context).push( MaterialPageRoute(builder: (_) => NovelReaderPage(novel: item.novel!)), ); return; } // 在线结果 — 🆕 改为跳转到详情页 final online = item.online; if (item.isError) { ScaffoldMessenger.of(context).showSnackBar( SnackBar(content: Text(item.errorMessage ?? '搜索失败,请稍后再试。')), ); return; } if (online == null) return; final source = ref.read(sourceManagerProvider).sourceById(online.sourceId); if (source == null) { ScaffoldMessenger.of(context).showSnackBar( const SnackBar(content: Text('书源已不可用。')), ); return; } // 🆕 跳转到在线书籍详情页 Navigator.of(context).push( MaterialPageRoute( builder: (_) => OnlineBookDetailPage( source: source, initialTitle: item.title, initialAuthor: item.author, initialCoverUrl: item.coverUrl, detailUrl: item.detailUrl ?? '', mode: mode, // manga 或 novel ), ), ); } ``` --- ### 5. 增加会话级内存缓存 **修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` 或新建独立缓存文件 **第一版用内存缓存即可,不要着急上 Hive/Isar。** ```dart /// 会话级内存缓存 class OnlineContentCache { // 存活时间:当次 APP 会话 final _bookInfoCache = {}; final _tocCache = >{}; final _chapterCache = {}; // 缓存 key 规则:source.id + URL String _key(String sourceId, String url) => '$sourceId|$url'; // BookInfo OnlineBookInfo? getBookInfo(String sourceId, String url) => _bookInfoCache[_key(sourceId, url)]; void putBookInfo(String sourceId, String url, OnlineBookInfo info) => _bookInfoCache[_key(sourceId, url)] = info; // TOC(章节列表) List? getToc(String sourceId, String tocUrl) => _tocCache[_key(sourceId, tocUrl)]; void putToc(String sourceId, String tocUrl, List chapters) => _tocCache[_key(sourceId, tocUrl)] = chapters; // Chapter(单章内容) OnlineChapterContent? getChapter(String sourceId, String chapterUrl) => _chapterCache[_key(sourceId, chapterUrl)]; void putChapter(String sourceId, String chapterUrl, OnlineChapterContent content) => _chapterCache[_key(sourceId, chapterUrl)] = content; // 预加载下一章(阅读器中调用) void preloadNextChapter(String sourceId, String nextUrl) { // 由阅读器在后台触发,不阻塞当前阅读 } void clear() { _bookInfoCache.clear(); _tocCache.clear(); _chapterCache.clear(); } } ``` **缓存策略**: - `BookInfo`:进入详情页时先查缓存,未命中才请求 - `TOC`:目录可能有几百章,每次进页面重新请求既慢也会增加书源站点压力——优先读缓存 - `ChapterContent`:只缓存当前章 + 预加载下一章,不要一口气缓存全部章节正文(容易占内存) **为什么阶段一不用持久化缓存**: - 在线书源的内容可能变化(网站改版、章节更新),持久化缓存容易导致过期数据 - 先跑通主流程,确认缓存策略合理后,P2 阶段再引入 Hive/Isar - 会话级缓存已能覆盖"用户在详情页和阅读器之间来回切换"的核心场景 --- ### 6. 章节识别器回退策略(替代盲扫 `` 标签) **修改位置**:`sakura_mobile/lib/src/core/legado_engine.dart` → 新增 `_chapterAwareFallback()` 方法 **问题**:原方案中的 `_fallbackSearchResults` 和自动扫描 `` 都太激进——会把导航链接、广告链接、面包屑链接都当成章节。 **改进**:引入"章节识别器"——即使用正则匹配章节标题特征,而非盲扫所有链接。 ```dart /// 章节标题特征正则 static final _chapterPatterns = [ // 中文数字章节 RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*[章节话卷回]'), // 中文数字话 RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*话'), // 纯数字章节 RegExp(r'第\s*\d+\s*[章节话卷回]'), // 英文章节 RegExp(r'Chapter\s*\d+', caseSensitive: false), RegExp(r'Episode\s*\d+', caseSensitive: false), // 卷 RegExp(r'Vol\.?\s*\d+', caseSensitive: false), RegExp(r'第\s*[\d零一二三四五六七八九十百千万]+\s*卷'), // 纯数字话 RegExp(r'^\d+\s*[话章]'), ]; /// 判断文本是否像一个章节标题 bool _looksLikeChapterTitle(String text) { final trimmed = text.trim(); if (trimmed.length < 2 || trimmed.length > 80) return false; for (final pattern in _chapterPatterns) { if (pattern.hasMatch(trimmed)) return true; } return false; } /// 回退目录解析:扫描 HTML 中的 标签,但只保留符合章节标题特征的 List _fallbackTocParser(String body, String baseUrl) { final seen = {}; final chapters = []; final links = RegExp( r"]*\bhref=[\"']([^\"']+)[\"'][^>]*>(.*?)", caseSensitive: false, dotAll: true, ).allMatches(body); for (final match in links) { final href = match.group(1)?.trim() ?? ''; if (href.isEmpty || href.startsWith('#') || href.toLowerCase().startsWith('javascript:')) continue; final title = _htmlToText(match.group(2) ?? ''); if (!_looksLikeChapterTitle(title)) continue; // ← 关键过滤 final url = _resolveUrl(baseUrl, href); if (url.isEmpty || !seen.add(url)) continue; chapters.add(OnlineChapter( title: title, url: url, index: chapters.length + 1, )); } return chapters; } ``` **解析优先级**: ``` 1. 如果 tocListRule 可用 → 使用规则解析(精确) 2. 如果 tocListRule 不可用 → 使用章节识别器扫描(降级但可控) 3. 返回结果 ≤ 2 条 → 不做二次请求,直接展示(可能书源确实只有少量章节,也可能是网站结构不支持回退解析) ``` --- ## 四、P1:第二阶段修改 > 这些依赖于 P0 的数据模型和详情页基础设施就绪。 ### 1. 阅读器改造成章节驱动 **修改位置**:`online_manga_reader_page.dart` 和 `online_novel_reader_page.dart` **当前**:读取器接收 `detailUrl`(其实是书籍详情页 URL),从中提取所有图片/文本。 **改造后**:读取器接收章节级参数。 ```dart class OnlineMangaReaderPage extends ConsumerStatefulWidget { const OnlineMangaReaderPage({ super.key, required this.source, required this.bookTitle, // 🆕 书名(用于 AppBar / 阅读记录) required this.chapters, // 🆕 完整章节列表 required this.currentChapterIndex,// 🆕 当前章节序号 this.currentChapterUrl, // 当前章节 URL(优先于从 chapters 取) }); final LegadoSource source; final String bookTitle; final List chapters; final int currentChapterIndex; final String? currentChapterUrl; } ``` **进入阅读器时的数据加载**: ``` 1. 从 chapters[currentChapterIndex].url 取章节 URL 2. 如果有 contentRule → 用 contentRule 解析 3. 如果没有 contentRule → 回退到现有的 fetchImageUrls / fetchPlainText 4. 用 contentNextRule 提取下一章 URL(优先于 chapters 数组) 5. 用 contentPrevRule 提取上一章 URL ``` **阅读器底部导航**: ``` ┌───────────┬───────────┬───────────┐ │ ← 上一章 │ 📋 目录 │ 下一章 → │ └───────────┴───────────┴───────────┘ ``` - "上一章":`currentChapterIndex > 0` 时才可用 - "下一章":`currentChapterIndex < chapters.length - 1` 或 `contentNextRule` 解析到了 URL 时才可用 - "目录":`Navigator.pop()` 回到详情页(章节列表已缓存,无需重新加载) --- ### 2. 支持目录分页 `{{page}}` **修改位置**:`legado_engine.dart` → 新增 `_fetchPaginatedToc()` 方法 **问题**:很多书源的目录是分页的,URL 模板包含 `{{page}}` 占位符,例如: ``` /chapterlist/123?page={{page}} ``` 如果不处理分页,只能拿到第一页的章节(通常几十章),后面几百章全部丢失。 **实现**: ```dart Future> _fetchPaginatedToc( LegadoSource source, String tocUrlTemplate, ) async { final allChapters = []; const maxPages = 20; // 防止死循环 String? nextPageUrl = tocUrlTemplate; for (int page = 1; page <= maxPages; page++) { // 1. 替换 {{page}} 占位符 final url = nextPageUrl! .replaceAll('{{page}}', page.toString()) .replaceAll('{page}', page.toString()); // 2. 请求并解析当前页 final body = await _fetchBody(source, url); final parser = RuleParser(body, baseUrl: source.url); // 3. 用规则解析章节条目 final fragments = _safeSelectList(parser, source.tocListRule); for (final fragment in fragments) { final name = _safeSelect(parser, fragment, source.tocNameRule); final chapterUrl = _safeSelect(parser, fragment, source.tocUrlRule); if (name.isNotEmpty && chapterUrl.isNotEmpty) { allChapters.add(OnlineChapter( title: name, url: _resolveUrl(url, chapterUrl), index: allChapters.length + 1, )); } } // 4. 检查是否有下一页 if (source.tocNextPageRule != null) { nextPageUrl = _safeSelect(parser, body, source.tocNextPageRule); if (nextPageUrl == null || nextPageUrl.isEmpty) break; // 没有下一页了 } else { // 如果没有 nextPageRule,尝试自动检测:如果当前页有 {{page}},则用 page+1 继续 if (!tocUrlTemplate.contains('{{page}}') && !tocUrlTemplate.contains('{page}')) { break; // URL 模板中没有分页占位符,不继续 } // 如果当前页返回的章节数与上一页相同,可能到底了,也停止 } } return allChapters; } ``` **自动停止条件**: - `tocNextPageRule` 返回空 → 停止 - 当前页返回 0 条新章节 → 停止 - 达到 `maxPages`(20 页)→ 停止并打日志 - 当前页与上一页完全重复 → 停止(防止环形分页) --- ### 3. 章节预加载 **修改位置**:阅读器页面 **策略**:阅读当前章节时,后台预加载下一章内容。 ``` 用户正在读第 3 章 │ ├─ 立即请求:第 3 章内容(用 contentRule 解析) │ └─ 后台请求:第 4 章内容(放入 chapterCache) │ └─ 用户点"下一章" → 缓存命中 → 秒切 ``` ```dart void _preloadNextChapter() { final nextIdx = currentChapterIndex + 1; if (nextIdx >= chapters.length) return; final nextChapter = chapters[nextIdx]; final cacheKey = cache.key(source.id, nextChapter.url); if (cache.getChapter(source.id, nextChapter.url) != null) return; // 已缓存 // 异步预加载,不阻塞当前渲染 _engine.fetchChapterContent(source, nextChapter.url) .then((content) { cache.putChapter(source.id, nextChapter.url, content); }) .catchError((_) { // 预加载失败静默忽略,用户点到下一章时再重试 }); } ``` **注意**: - 只预加载**下一章**,不要一口气预加载全部(几百章的图片会爆内存) - 预加载失败静默忽略,点击"下一章"时再重新请求 --- ### 4. 阅读记录 **新增数据模型**: ```dart class OnlineReadingRecord { final String sourceId; final String sourceName; final String bookTitle; final String detailUrl; final String chapterUrl; final String chapterTitle; final int chapterIndex; final int totalChapters; final DateTime lastReadTime; } ``` **存储方式(P1 阶段)**:SharedPreferences 存储 JSON 数组,最多保留 50 条最近记录。 **用途**: - 「继续阅读」入口(在 ExplorePage 或首页) - 章节已读标记(在详情页章节列表中显示 ✓ 或灰色) - 返回详情页时自动定位到上次阅读的章节 **记录时机**: - 进入某章阅读 → upsert 阅读记录 - 切换章节 → 更新阅读记录 - 返回详情页 → 不记录(只记录"阅读"行为) --- ## 五、P2:后续增强 > 主流程稳定后再做这些。 ### 1. 持久化缓存 从内存缓存升级到本地持久化: | 方案 | 适用场景 | |------|---------| | **Hive** | 轻量,适合存储 BookInfo / TOC / 阅读记录 | | **Isar** | 功能更强,适合存储章节缓存 + 全文搜索 | | **SQLite / sqflite** | 最灵活,适合复杂查询(按书源查、按时间查等) | 建议:**Hive** 作为第一选择,因为数据模型简单且已广泛用于 Flutter 缓存场景。 持久化内容: - `BookInfo` → 按 `sourceId + detailUrl` 存储,有效期 24 小时 - `TOC` → 按 `sourceId + tocUrl` 存储,有效期 12 小时 - `阅读记录` → 永久存储,最多 200 条 - 章节内容 → 只缓存最近阅读的 20 章 ### 2. ContentType 支持 初期不需要设计 `enum ContentType { text, image, mixed }`。 因为已有 `bookSourceType`: - `type == 0` → 小说 → `contentRule` 提取文本 - `type == 2` → 漫画 → `contentRule` 提取图片 `mixed` 类型(小说中插图片、漫画中插文字)可以后期再支持。 ### 3. 高级 Legado 规则支持 后续逐步补充: - JSONPath 规则(`$.data.chapters[*]`) - Regex 规则(`regex:...`) - `webJs` 规则(需要 WebView 执行 JS 后取结果) - `replaceRegex`(正文净化,去广告/去水印) - 图片解密(部分漫画网站对图片做了简单加密,需要 JS 解密后 base64 展示) 这些是 Legado 生态的高级功能,不影响主体流程,可以逐步按需实现。 ### 4. 更完整的兼容测试 - 覆盖至少 10 个不同类型的书源(小说/漫画、GBK/UTF-8、分页/单页目录) - 测试老书源(只有搜索规则,没有 `ruleBookInfo` / `ruleToc`)的回退表现 - 测试网络异常情况(超时、DNS 失败、404、403) --- ## 六、优先级总表 ``` P0:必须优先修改 ├─ 1. unknown:none 错误归一化 ├─ 2. 扩展 LegadoSource 模型(ruleBookInfo / ruleToc / ruleContent) ├─ 3. 新增 OnlineBookDetailPage(合并 BookInfo + TOC UI) ├─ 4. BookInfo + TOC 分段异步加载 ├─ 5. 搜索结果点击进入详情页(explore_page.dart 导航逻辑) ├─ 6. 会话级内存缓存(BookInfo / TOC / Chapter) └─ 7. 章节识别器回退策略(替代盲扫 ) P1:第二阶段修改 ├─ 1. 阅读器改造成章节驱动(接收 chapters + currentChapterIndex) ├─ 2. contentRule 正式接入(提取章节正文/图片) ├─ 3. 目录分页 {{page}} 支持 ├─ 4. 下一章预加载 └─ 5. 阅读记录(继续阅读 / 已读标记) P2:后续增强 ├─ 1. 持久化缓存(Hive) ├─ 2. ContentType / mixed 内容 ├─ 3. 高级 Legado 规则支持(JSONPath / webJs / replaceRegex) └─ 4. 更完整的兼容测试 ``` --- ## 七、页面与数据流设计 ### 7.1 整体架构 ``` ┌─────────────────────────────────────────────────────────┐ │ 在线搜索 (ExplorePage) │ │ 输入关键词 → 并发搜索已启用的书源 → 展示结果列表 │ └───────────────────────┬─────────────────────────────────┘ │ 用户点击某本书 ▼ ┌─────────────────────────────────────────────────────────┐ │ 在线书籍详情页 (OnlineBookDetailPage) 🆕 │ │ │ │ ┌─── 上半部分:BookInfo ───┐ │ │ │ 封面 · 书名 · 作者 · 来源 │ ← 第一步加载 │ │ │ 状态 · 简介 │ │ │ │ [开始阅读] [保存到书架] │ │ │ └──────────────────────────┘ │ │ │ │ ┌─── 下半部分:TOC ────────┐ │ │ │ 章节目录 (共 336 章) │ ← 第二步加载(独立请求) │ │ │ [正序] [倒序] │ │ │ │ 第一章 · 第二章 · ... │ 支持分页加载 │ │ └──────────────────────────┘ │ └───────────────────────┬─────────────────────────────────┘ │ 点击某章节 ▼ ┌─────────────────────────────────────────────────────────┐ │ 在线阅读器 (MangaReader / NovelReader) 🔧 改造 │ │ │ │ AppBar: 第3话 / 共336话 │ │ 正文内容 / 漫画图片 │ │ [← 上一章] [📋 目录] [下一章 →] │ │ │ │ 接收参数: source, chapters, currentChapterIndex │ │ 预加载: 下一章内容(后台) │ │ 记录: 阅读进度 │ └─────────────────────────────────────────────────────────┘ ``` ### 7.2 数据流 ``` 阶段 1 — 搜索: LegadoSource.searchUrl + keyword → HTTP GET/POST → searchListRule 提取条目列表 → 每个条目: {title, author, coverUrl, detailUrl} 阶段 2 — 详情(先): detailUrl → HTTP GET → bookInfoRule 提取: {name, author, cover, intro, tocUrl} → 存入 bookInfoCache → 渲染页面顶部 阶段 3 — 目录(后): tocUrl → HTTP GET(支持 {{page}} 分页) → chapterListRule 提取: [{name, url}, ...] → 存入 tocCache → 渲染章节列表 阶段 4 — 阅读: chapter.url → HTTP GET → contentRule 提取: 正文文本 / 漫画图片 URL 列表 → 存入 chapterCache → 展示内容 → 后台预加载下一章 ``` ### 7.3 路由变更 | 当前 | 改造后 | |------|--------| | ExplorePage → OnlineMangaReaderPage(detailUrl) ❌ | ExplorePage → **OnlineBookDetailPage(detailUrl)** → 点击章节 → OnlineMangaReaderPage(chapterUrl) ✅ | | ExplorePage → OnlineNovelReaderPage(detailUrl) ❌ | ExplorePage → **OnlineBookDetailPage(detailUrl)** → 点击章节 → OnlineNovelReaderPage(chapterUrl) ✅ | --- ## 八、数据模型扩展 ### 8.1 LegadoSource 新增字段 ```dart class LegadoSource { // ===== 现有字段(保持不变)===== final String id; final String name; final String url; final int type; // 0=小说, 2=漫画 final bool enabled; final String? userAgent; final Map headers; final String? searchUrl; final String? searchListRule; final String? searchNameRule; final String? searchAuthorRule; final String? searchCoverRule; final String? searchDetailRule; final String? searchMethod; final String? searchBody; final String? ruleKind; final String? charset; final String? urlEncoding; // ===== 🆕 BookInfo ===== final String? bookInfoUrl; final String? bookInfoNameRule; final String? bookInfoAuthorRule; final String? bookInfoCoverRule; final String? bookInfoIntroRule; final String? bookInfoTocRule; // ⭐ 最关键:目录页 URL // ===== 🆕 TOC ===== final String? tocUrl; final String? tocListRule; final String? tocNameRule; final String? tocUrlRule; final String? tocNextPageRule; // 目录分页 // ===== 🆕 Content ===== final String? contentRule; final String? contentNextRule; final String? contentPrevRule; } ``` ### 8.2 新增运行时数据模型 ```dart /// 在线书籍详情 class OnlineBookInfo { final String title; final String? author; final String? coverUrl; final String? intro; final String tocUrl; // ⭐ 目录页 URL final String? status; // 连载中/已完结 final String? category; final String? updateTime; final String sourceName; // 来源书源名称 } /// 在线章节 class OnlineChapter { final String title; final String url; final int index; // 从 1 开始 bool isRead; // 是否已读(阅读记录反填) } /// 在线章节内容 class OnlineChapterContent { final String title; final String? textContent; // 小说正文 final List? imageUrls; // 漫画图片 final String? nextChapterUrl; // 下一章 URL(contentNextRule 解析结果) final String? prevChapterUrl; // 上一章 URL } /// 阅读记录 class OnlineReadingRecord { final String sourceId; final String sourceName; final String bookTitle; final String detailUrl; final String chapterUrl; final String chapterTitle; final int chapterIndex; final int totalChapters; final DateTime lastReadTime; } ``` ### 8.3 fromJson / copyWith / toJson 变更 - `fromJson`:新增 12 个字段的解析逻辑(见上文 P0-2) - `copyWith`:新增 12 个字段的传递(确保 `setEnabled()` 等不丢失数据) - `toJson`:新增 12 个字段的序列化(确保持久化到 SharedPreferences 时保留) --- ## 九、Legado 书源规则字段对照 ### 9.1 完整的 Legado 书源 JSON 示例 ```json { "bookSourceName": "示例书源", "bookSourceUrl": "https://www.example.com", "bookSourceType": 0, "bookSourceCharset": "gbk", "ruleSearch": { "url": "/search?keyword={{key}}&page={{page}}", "bookList": ".result-list .item", "name": ".book-title", "author": ".author", "coverUrl": "img@src", "detailUrl": "a@href" }, "ruleBookInfo": { "name": "h1.book-title", "author": ".author span", "coverUrl": ".book-cover img@src", "intro": ".book-desc", "tocUrl": ".catalog-btn@href" }, "ruleToc": { "chapterList": ".chapter-list li", "chapterName": "a", "chapterUrl": "a@href", "nextTocUrl": ".next-page@href" }, "ruleContent": { "content": "#chapter-content", "nextChapterUrl": ".next-chapter@href", "prevChapterUrl": ".prev-chapter@href" } } ``` ### 9.2 字段映射表 | Legado 字段路径 | Sakura LegadoSource 字段 | P0/P1 | |----------------|-------------------------|-------| | `bookSourceName` | `name` | ✅ 已有 | | `bookSourceUrl` | `url` | ✅ 已有 | | `bookSourceType` | `type` | ✅ 已有 | | `bookSourceCharset` | `charset` | ✅ 已有 | | `ruleSearch.url` | `searchUrl` | ✅ 已有 | | `ruleSearch.bookList` | `searchListRule` | ✅ 已有 | | `ruleSearch.name` | `searchNameRule` | ✅ 已有 | | `ruleSearch.author` | `searchAuthorRule` | ✅ 已有 | | `ruleSearch.coverUrl` | `searchCoverRule` | ✅ 已有 | | `ruleSearch.detailUrl` | `searchDetailRule` | ✅ 已有 | | `ruleBookInfo.name` | `bookInfoNameRule` | 🆕 P0 | | `ruleBookInfo.author` | `bookInfoAuthorRule` | 🆕 P0 | | `ruleBookInfo.coverUrl` | `bookInfoCoverRule` | 🆕 P0 | | `ruleBookInfo.intro` | `bookInfoIntroRule` | 🆕 P0 | | `ruleBookInfo.tocUrl` | `bookInfoTocRule` | 🆕 P0 ⭐ | | `ruleToc.chapterList` | `tocListRule` | 🆕 P0 | | `ruleToc.chapterName` | `tocNameRule` | 🆕 P0 | | `ruleToc.chapterUrl` | `tocUrlRule` | 🆕 P0 | | `ruleToc.nextTocUrl` | `tocNextPageRule` | 🆕 P1 | | `ruleContent.content` | `contentRule` | 🆕 P1 | | `ruleContent.nextChapterUrl` | `contentNextRule` | 🆕 P1 | | `ruleContent.prevChapterUrl` | `contentPrevRule` | 🆕 P1 | --- ## 十、附录:关键文件清单 ### 修改的文件 | 文件 | 角色 | P0 | P1 | P2 | |------|------|:--:|:--:|:--:| | `sakura_mobile/lib/src/core/legado_models.dart` | 数据模型 | 🔧 | | | | `sakura_mobile/lib/src/core/legado_engine.dart` | 解析引擎 | 🔧 | 🔧 | 🔧 | | `sakura_mobile/lib/src/core/legado_rule_parser.dart` | 规则解析器 | | | | | `sakura_mobile/lib/src/pages/explore_page.dart` | 搜索页导航 | 🔧 | | | | `sakura_mobile/lib/src/pages/online_manga_reader_page.dart` | 漫画阅读器 | | 🔧 | | | `sakura_mobile/lib/src/pages/online_novel_reader_page.dart` | 小说阅读器 | | 🔧 | | | `sakura_mobile/lib/src/core/providers.dart` | Riverpod | 视需要 | | | ### 新增的文件 | 文件 | 角色 | P0 | P1 | P2 | |------|------|:--:|:--:|:--:| | `sakura_mobile/lib/src/pages/online_book_detail_page.dart` | 在线书籍详情页(合并 UI) | 🆕 | | | | `sakura_mobile/lib/src/core/online_cache.dart` | 会话级内存缓存 | 🆕 | | | --- ## 总结 以「能落地开发」为最终目标,本方案的核心建议是: 1. **先修 `_shortError()`** — 把 `unknown:none` 等所有 Dio 底层异常映射为中文提示,这是最小的改动但立刻消除最明显的 bug。 2. **再补模型** — `LegadoSource` 补全 `ruleBookInfo`、`ruleToc`、`ruleContent` 字段,`fromJson`/`copyWith`/`toJson` 全部对齐。不补齐模型,后面所有的页面都无从谈起。 3. **再做合并式详情页** — `OnlineBookDetailPage` 把 BookInfo + TOC 放在同一个页面,但数据加载分两次独立请求。不跳独立 TOC 页面,用户体验更流畅。 4. **接章节阅读** — 阅读器接收 `chapters` + `currentChapterIndex`,从 URL 驱动改成章节驱动。这是解决"点开书直接显示乱码"问题的终点。 5. **最后补分页和高级规则** — 目录分页 `{{page}}`、章节预加载、阅读记录、持久化缓存——这些让体验从"能用"到"好用"。 ``` 页面合并,解析分层; 缓存前置,持久化后置; 目录回退要识别章节,不要盲扫链接; 阅读器必须从 URL 驱动改成章节驱动。 ```