Files
SakuraHub/docs/漫画源问题.md
T

778 lines
17 KiB
Markdown
Raw Normal View History

2026-11-16 20:45:22 +08:00
下面是整合后的**最终完整方案**,包括:漫画解析、章节完整性、图片加载、调试能力、搜索性能,以及你刚刚提到的顶部搜索框 UI 问题。
Sakura 漫画模块完整改进方案
=================
一、改进目标
------
本轮改造解决 5 类问题:
1. 漫画章节目录不全
2. 漫画图片解析失败
3. 图片 URL 有数量但无法显示
4. 在线搜索速度慢
5. 漫画 / 图片页顶部搜索框布局异常,在线搜索入口位置不合理
* * *
二、整体优先级
=======
P0:顶部搜索框 UI 修复与在线搜索入口重构
P1:图片 URL 合法性验证
P2:PageImage + headers 拆分
P3:图片 HTTP 探测与调试能力
P4:TOC 分页抓全章节
P5:章节排序支持番外
P6:Script 图片变量提取
P7:漫画调试页
P8:搜索健康分与增量搜索
说明:
P0 先做,因为它是明显 UI 问题,改动小、收益快。
P1~P7 解决漫画“能不能看”。
P8 最后做,解决“搜得慢”。
* * *
P0:顶部搜索框 UI 修复与在线搜索入口重构
=======================
问题
--
截图中红框区域出现:
顶部搜索栏被状态栏 / 右上角按钮挤压
漫画页和图片页都出现同类问题
在线搜索入口放在右上角,不符合用户预期
目标
--
漫画页 / 图片页顶部布局稳定
搜索框不被状态栏遮挡
在线搜索入口集成到搜索框流程中
不再在右上角放在线搜索按钮
推荐交互
----
页面顶部只保留一个统一搜索框:
[ 搜索图标 ] 搜索标题、作者或标签 [筛选] [刷新]
点击搜索框进入统一搜索页:
SearchPage
├─ 搜索输入框
├─ 搜索范围切换:本地 / 在线 / 全部
└─ 结果分区:
├─ 本地漫画
├─ 在线漫画源
└─ 图片 / 插画
代码结构
----
新增统一组件:
class SakuraSearchBar extends StatelessWidget {
final String hintText;
final VoidCallback onTap;
final VoidCallback? onFilterTap;
final VoidCallback? onRefreshTap;
const SakuraSearchBar({
super.key,
required this.hintText,
required this.onTap,
this.onFilterTap,
this.onRefreshTap,
});
@override
Widget build(BuildContext context) {
return Material(
elevation: 6,
borderRadius: BorderRadius.circular(32),
color: Theme.of(context).colorScheme.surface,
child: InkWell(
borderRadius: BorderRadius.circular(32),
onTap: onTap,
child: SizedBox(
height: 56,
child: Row(
children: [
const SizedBox(width: 18),
const Icon(Icons.search),
const SizedBox(width: 12),
Expanded(
child: Text(
hintText,
maxLines: 1,
overflow: TextOverflow.ellipsis,
style: Theme.of(context).textTheme.titleMedium,
),
),
if (onFilterTap != null)
IconButton(
icon: const Icon(Icons.tune),
onPressed: onFilterTap,
),
if (onRefreshTap != null)
IconButton(
icon: const Icon(Icons.refresh),
onPressed: onRefreshTap,
),
const SizedBox(width: 8),
],
),
),
),
);
}
}
页面顶部必须用:
SafeArea(
bottom: false,
child: Padding(
padding: const EdgeInsets.fromLTRB(16, 8, 16, 8),
child: SakuraSearchBar(
hintText: '搜索标题、作者或标签',
onTap: () {
Navigator.push(
context,
MaterialPageRoute(
builder: (_) => UnifiedSearchPage(
initialMode: SearchMode.manga,
),
),
);
},
onFilterTap: _openFilter,
onRefreshTap: _refresh,
),
),
)
禁止再用:
Stack + Positioned 顶部硬定位
AppBar 右上角塞在线搜索入口
状态栏高度手动写死
* * *
P1:图片 URL 合法性验证
===============
目标
--
不要相信 `1/17` 这种页数。它可能是:
17 个真实图片
17 个空字符串
17 个 loading 图
17 个 placeholder
17 个错误 URL
新增模型:
class ImageCandidate {
final String raw;
final String? url;
final bool isValid;
final String? reason;
const ImageCandidate({
required this.raw,
required this.url,
required this.isValid,
this.reason,
});
}
验证逻辑:
ImageCandidate validateImageCandidate(String raw, String baseUrl) {
final value = raw.trim();
if (value.isEmpty) {
return ImageCandidate(
raw: raw,
url: null,
isValid: false,
reason: 'empty',
);
}
if (value.startsWith('data:')) {
return ImageCandidate(
raw: raw,
url: null,
isValid: false,
reason: 'data-uri',
);
}
final lower = value.toLowerCase();
if (lower.contains('loading') ||
lower.contains('placeholder') ||
lower.contains('logo') ||
lower.contains('icon')) {
return ImageCandidate(
raw: raw,
url: value,
isValid: false,
reason: 'placeholder',
);
}
final normalized = normalizeImageUrl(value, baseUrl);
final uri = Uri.tryParse(normalized);
if (uri == null || !uri.hasScheme || uri.host.isEmpty) {
return ImageCandidate(
raw: raw,
url: normalized,
isValid: false,
reason: 'invalid-url',
);
}
return ImageCandidate(
raw: raw,
url: normalized,
isValid: true,
);
}
URL 归一化:
String normalizeImageUrl(String raw, String baseUrl) {
var u = raw.trim()
.replaceAll(r'\/', '/')
.replaceAll(r'\u002F', '/');
if (u.startsWith('//')) {
u = 'https:$u';
}
return Uri.parse(baseUrl).resolve(u).toString();
}
* * *
P2:PageImage + headers 拆分
=========================
问题
--
Legado 漫画源经常返回:
https://xxx.jpg,{"headers":{"Referer":"https://site.com"}}
如果直接丢给:
Image.network(raw)
图片必炸。
新模型
---
class PageImage {
final int index;
final String raw;
final String url;
final Map<String, String> headers;
const PageImage({
required this.index,
required this.raw,
required this.url,
required this.headers,
});
}
拆分逻辑
----
class ParsedImageSpec {
final String url;
final Map<String, String> headers;
ParsedImageSpec({
required this.url,
required this.headers,
});
}
ParsedImageSpec splitLegadoImageSpec(String raw) {
final idx = raw.indexOf(',{');
if (idx < 0) {
return ParsedImageSpec(url: raw.trim(), headers: {});
}
final url = raw.substring(0, idx).trim();
final jsonText = raw.substring(idx + 1).trim();
final headers = <String, String>{};
try {
final decoded = jsonDecode(jsonText);
final h = decoded['headers'];
if (h is Map) {
h.forEach((k, v) {
headers[k.toString()] = v.toString();
});
} else if (h is String) {
final inner = jsonDecode(h);
if (inner is Map) {
inner.forEach((k, v) {
headers[k.toString()] = v.toString();
});
}
}
} catch (_) {}
return ParsedImageSpec(url: url, headers: headers);
}
生成 PageImage:
PageImage buildPageImage({
required String raw,
required String chapterUrl,
required LegadoSource source,
required int index,
}) {
final parsed = splitLegadoImageSpec(raw);
final headers = <String, String>{
...source.headers,
'User-Agent': source.userAgent ?? defaultUserAgent,
'Referer': chapterUrl,
...parsed.headers,
};
return PageImage(
index: index,
raw: raw,
url: normalizeImageUrl(parsed.url, chapterUrl),
headers: headers,
);
}
阅读器改成:
Image.network(
page.url,
headers: page.headers,
fit: BoxFit.contain,
errorBuilder: (_, error, stack) {
return const Icon(Icons.broken_image);
},
)
* * *
P3:图片 HTTP 探测
=============
目标
--
判断到底是:
URL 错
headers 错
反爬
图片损坏
Flutter 缓存问题
新增:
class ImageProbeResult {
final String url;
final int? statusCode;
final String? contentType;
final int contentLength;
final String first16BytesHex;
final bool looksLikeImage;
final String? error;
const ImageProbeResult({
required this.url,
this.statusCode,
this.contentType,
required this.contentLength,
required this.first16BytesHex,
required this.looksLikeImage,
this.error,
});
}
探测:
Future<ImageProbeResult> probeImage(Dio dio, PageImage image) async {
try {
final resp = await dio.get<List<int>>(
image.url,
options: Options(
responseType: ResponseType.bytes,
headers: image.headers,
validateStatus: (_) => true,
),
);
final bytes = resp.data ?? const <int>[];
final first16 = bytes
.take(16)
.map((b) => b.toRadixString(16).padLeft(2, '0'))
.join();
return ImageProbeResult(
url: image.url,
statusCode: resp.statusCode,
contentType: resp.headers.value('content-type'),
contentLength: bytes.length,
first16BytesHex: first16,
looksLikeImage: isImageMagic(bytes),
);
} catch (e) {
return ImageProbeResult(
url: image.url,
contentLength: 0,
first16BytesHex: '',
looksLikeImage: false,
error: e.toString(),
);
}
}
魔数判断:
bool isImageMagic(List<int> b) {
if (b.length < 4) return false;
// JPG
if (b[0] == 0xFF && b[1] == 0xD8 && b[2] == 0xFF) return true;
// PNG
if (b[0] == 0x89 && b[1] == 0x50 && b[2] == 0x4E && b[3] == 0x47) {
return true;
}
// WEBP
if (b.length >= 12 &&
b[0] == 0x52 &&
b[1] == 0x49 &&
b[2] == 0x46 &&
b[3] == 0x46 &&
b[8] == 0x57 &&
b[9] == 0x45 &&
b[10] == 0x42 &&
b[11] == 0x50) {
return true;
}
// GIF
if (b[0] == 0x47 && b[1] == 0x49 && b[2] == 0x46 && b[3] == 0x38) {
return true;
}
// BMP
if (b[0] == 0x42 && b[1] == 0x4D) return true;
return false;
}
诊断表:
403 / 444
→ Referer / User-Agent / Cookie 问题
404
→ 图片 URL 拼错或章节页已失效
200 + text/html
→ 反爬页 / 登录页 / 错误页
200 + image/* + contentLength < 1024
→ 可能是伪装错误图或破损图
200 + image/* + 魔数失败
→ 响应不是有效图片
200 + image/* + 魔数成功但 Image.network 不显示
→ headers 没传进 Image.network / 图片缓存污染 / Flutter 图片组件问题
* * *
P4:TOC 分页抓全章节
=============
问题
--
一人之下 600+ 话,但现在只显示几十章,说明目录分页没有抓全。
支持字段
----
tocNextPageRule
nextTocUrl
nextUrl
nextPage
tocNextPage
抓取流程
----
firstTocUrl
→ 请求当前页
→ 解析 chapterList
→ 解析 nextTocUrl
→ resolve 成绝对 URL
→ 合并章节并去重
→ 继续下一页
终止条件
----
nextUrl == null
seenPageUrls 已访问
连续 2 页新增章节为 0
pageCount >= 100
chapterCount >= 3000
建议参数:
const maxTocPages = 100;
const maxTocChapters = 3000;
const emptyPageDelay = Duration(milliseconds: 500);
* * *
P5:章节排序支持番外
===========
支持:
第660话
第660.5回
Ch.660
ch 660.5
660话
660.5 番外
章节号提取:
double? extractChapterNo(String title) {
var m = RegExp(r'第\s*(\d+(?:\.\d+)?)\s*[回话章节节]').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
m = RegExp(r'[Cc]h\.?\s*(\d+(?:\.\d+)?)').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
m = RegExp(r'^\s*(\d+(?:\.\d+)?)\s*(?:话|回|章|节)?').firstMatch(title);
if (m != null) return double.tryParse(m.group(1)!);
return null;
}
排序:
chapters.sort((a, b) {
final na = extractChapterNo(a.title);
final nb = extractChapterNo(b.title);
if (na != null && nb != null && na != nb) {
return na.compareTo(nb);
}
return a.index.compareTo(b.index);
});
* * *
P6:Script 图片变量提取
================
当 `ruleContent.content` 失败或候选图片全无效时,从 rawHtml 的 script 中提取图片。
支持变量:
newImgs
imageList
page_url
chapterImages
photosr
img_data
picTree
示例:
List<String> extractImagesFromScripts(String html) {
final out = <String>[];
final patterns = [
RegExp(r'newImgs\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'imageList\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'"page_url"\s*:\s*(\[[\s\S]*?\])'),
RegExp(r'chapterImages\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'photosr\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'img_data\s*=\s*(\[[\s\S]*?\])'),
RegExp(r'picTree\s*=\s*(\[[\s\S]*?\])'),
];
for (final p in patterns) {
final m = p.firstMatch(html);
if (m == null) continue;
final raw = m.group(1)!;
final list = tryDecodeStringList(raw);
out.addAll(list.map(sanitizeScriptUrl));
}
return out;
}
清洗:
String sanitizeScriptUrl(String url) {
return url
.replaceAll(r'\/', '/')
.replaceAll(r'\u002F', '/');
}
* * *
P7:漫画调试页
========
入口
--
书籍详情页 → 长按章节 → 调试本章
阅读器右上角菜单 → 调试当前章
展示内容
----
{
"sourceName": "包子漫画5",
"bookTitle": "一人之下",
"chapterTitle": "第652回",
"chapterUrl": "...",
"ruleContent": "...",
"rawHtmlLength": 123456,
"contentOutputLength": 2048,
"rawCandidateCount": 17,
"validCandidateCount": 0,
"pageImageCount": 0,
"firstCandidates": [
{
"raw": "...",
"normalized": "...",
"reason": "placeholder"
}
],
"probe": [
{
"url": "...",
"status": 200,
"contentType": "image/jpeg",
"contentLength": 312,
"first16Bytes": "ffd8ff...",
"looksLikeImage": false
}
]
}
操作按钮
----
复制调试信息
重新检测前 5 张图
切换 Referer:章节页 / 详情页 / 源首页
清除图片缓存后重试
打开原始章节 URL
* * *
P8:搜索健康分与增量搜索
=============
问题
--
搜索慢主要来自:
坏源太多
每个源 timeout 太长
所有源一起等结果
模型
--
class SourceHealth {
final String sourceId;
int successCount = 0;
int failCount = 0;
int timeoutCount = 0;
int totalLatencyMs = 0;
int consecutiveFails = 0;
DateTime? lastSuccessAt;
DateTime? lastFailAt;
}
策略
--
健康源优先
坏源降权
连续失败 >= 5 临时跳过
搜索超时 5~8 秒
快速源先返回
慢源后台补充
搜索阶段
----
0~5s:快速源结果
5~8s:普通源结果
8s 后:慢源后台补
* * *
三、最终落地顺序
========
第 1 阶段:UI 先止血
-------------
P0:顶部搜索框 UI 修复
P0:在线搜索入口放进统一搜索页
结果:
漫画页 / 图片页顶部不再错位
在线搜索不再占右上角
搜索体验统一
第 2 阶段:图片链路可观测
--------------
P1:图片 URL 合法性验证
P2:PageImage + headers 拆分
P3:图片 HTTP 探测
P7:漫画调试页
结果:
可以准确判断图片失败原因
不再靠猜
第 3 阶段:章节抓全
-----------
P4:TOC 分页
P5:章节排序
结果:
一人之下这类 600+ 话漫画可以抓全
章节顺序稳定
第 4 阶段:提升漫画源覆盖率
---------------
P6:Script 图片变量提取
结果:
更多漫画源能解析图片
第 5 阶段:优化搜索速度
-------------
P8:搜索健康分与增量搜索
结果:
坏源不拖慢搜索
结果更快出现
* * *
=======