Files
SakuraHub/docs/漫画源问题.md
2026-11-16 20:45:22 +08:00

779 lines
17 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
下面是整合后的**最终完整方案**,包括:漫画解析、章节完整性、图片加载、调试能力、搜索性能,以及你刚刚提到的顶部搜索框 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:搜索健康分与增量搜索
结果:
坏源不拖慢搜索
结果更快出现
* * *
=======