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

17 KiB
Raw Blame History

下面是整合后的最终完整方案,包括:漫画解析、章节完整性、图片加载、调试能力、搜索性能,以及你刚刚提到的顶部搜索框 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 probeImage(Dio dio, PageImage image) async { try { final resp = await dio.get<List>( 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 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 extractImagesFromScripts(String html) { final out = [];

  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:搜索健康分与增量搜索

结果: 坏源不拖慢搜索 结果更快出现


=======