如何为红果鉴编写视频站源:从零接入一个新源的实战教程

原创2026-11-05 01:26:093,428 阅读
文章标签:音视频视频移动开发桌面应用跨平台

如何为红果鉴编写视频站源:从零接入一个新源的实战教程

红果鉴 / 真果鉴是一款 Flutter 多端短剧客户端,内置红果、韩小圈、鬼片、青空、野果等十几个视频站源。如果你想为红果鉴贡献一个新的视频站源,本文是一份从零开始的实战教程:先讲清"站源"在红果鉴架构里的位置,再用仓库里"野果"站源的完整代码为例,带你走完登记站点、接入目录与详情、解析播放地址、注册到界面的全部步骤,并附常见坑位清单和构建验证方法,帮你快速写出一个可用的新站源。

红果鉴短剧客户端品牌横幅,含多端播放图标与应用名称

一、先搞懂架构:站源为什么写在 Go 里

很多客户端的"站源"是 JSON 或脚本,但红果鉴的站源是 Go 原生 provider,不是运行期加载的脚本(见 DEVELOPMENT.md 的"站源开发约定")。整体分工是这样的:

  • Flutter 界面层(lib/):只负责界面、播放器和本地用户数据;
  • Go 原生核心(native/core):站源请求、解析、签名、缓存、下载调度和播放代理全部在这里完成;
  • FFI 桥接(native/bridge/main.go):对外只导出 DuanjuRequest(json) -> json 与 DuanjuFree 两个符号,Dart 侧 core_bridge.dart 把每次调用编码成 {"action": ...} 请求,Go 侧按 action 分派。

也就是说,新增一个站源 = 新增一套 Go provider 代码 + 在若干分发点登记 + 在 Dart 侧登记站点名。下面以"野果"站源为参照模板,逐个拆解。

二、接入清单:一个新站源要改哪些文件

官方在 DEVELOPMENT.md 中列出的接入点如下,这也是本文的路线图:

步骤 文件 要做什么
1 provider_huangguo.go 定义 sourceXxx 常量,加入白名单与 canonicalProviderSource 反查
2 provider_yeguo.go / provider_yeguo_client.go 编写该站的目录、详情、播放解析代码
3 provider_media.go 登记 baseURL 默认值与 host 反查
4 app_categories.go 接入分类 Tab
5 app_cover_metadata.go 封面 URL 补全规则
6 app_runtime.go Config 字段 + 目录 / 搜索 / 详情分派
7 lib/models.dart Dart 侧登记 SourceSite

💡 小技巧:写之前先在 native/core 里通读一个最简单的站源(比如"野果"或"帝果"),照抄结构再改字段,比从头造轮子快得多。

三、以"野果"为例:目录、详情与播放三段式

3.1 站点常量与客户端封装

每个站源先定义自己的来源 ID 常量,如 provider_huangguo.go 中的 sourceYeguo = "yeguo",并在 isHuangguoProviderSource 白名单和 canonicalProviderSource 里登记(支持按域名反推来源,如 ygdj15.com → 野果)。

客户端封装一般单独放一个文件。野果的 provider_yeguo_client.go 维护了一个 yeguoAPIClient,负责 baseURL(默认 https://analyze.buxefaex.cc,见 provider_yeguo.go)、加密参数、响应解码和缓存——如果新站是纯公开 JSON API,这一层可以写得很薄;如果源站有签名或加密(比如 AES 解密、JS 里取 baseURL),就都放在这里。

3.2 目录与搜索:fetchXxxCatalogPage

目录函数返回 (<a href="https://link.gitcode.com/i/c4aa52f11dea9bfbf603a8486da1031e" target="_blank">]Drama, hasMore, error),模式固定(见 [fetchYeguoCatalogPage):

  1. 校验页码、分类、关键词等入参,非法直接返回错误;
  2. 调用接口(搜索走 /api/search/result,分类走 /api/theater/exploreList),拿到 JSON 数组;
  3. 逐行转成 Drama 结构体,ID 统一用 providerDramaID(source, id) 拼成 站源:源站ID 形式;
  4. 用 total / has_more / 每页条数推断 hasMore。

注意代码里对"重复剧集""条目过多""分页信息无效"都做了显式报错——这是项目一贯的防御风格,新站源建议保持同样的严格度。

3.3 详情与选集:fetchXxxDetail

详情函数返回 (Drama, <a href="https://link.gitcode.com/i/d22d008fd46705e31d0f0c688b05a375" target="_blank">]Chapter, error),见 [fetchYeguoDetail。要点:

  • 每一集生成一个 Chapter,ID 用 providerChapterID(source, sourceID, episodeID) 三段式;
  • 分集按集数排序、去重,广告集(is_adv)直接跳过;
  • 播放地址可以先不解析,存一个 yeguo-play://集ID 这样的自定义协议占位,真正解析留给播放阶段(下面讲)。

3.4 播放地址解析:resolveXxxMedia

播放时 Go 核心调用 resolveProviderMedia 分派到各站源的 resolveXxxMedia。野果的实现 resolveYeguoMedia 展示了完整套路:

  1. 从 Chapter.ID 反解出剧集 ID 和集 ID;
  2. 调用播放接口拿到真正的视频地址(video_url / video_url_h265);
  3. 校验返回数据与请求一致(防止站源串集);
  4. 组装 providerMedia{URL, Referer, Quality, Duration},多清晰度放进 Variants。

对于页面里内嵌播放地址(如 HLS 的 data-hls、m3u8 链接)的站源,则可以直接在详情阶段用正则从 HTML 里抠出来,参考 provider_huangguo.go 里的一组正则。

⚠️ 正则大坑:Go 用的是 RE2,不支持 lookahead。解析多线路播放列表时不能用 (?=...) 分段(会消耗下一段开头),应改用显式字符串截断:先定位容器标记,再在其后查找下一段标记。这是项目文档明确强调的约定。

3.5 分类与封面

  • 分类:在 app_categories.go 的 nativeCategories 分派中新增 case sourceXxx,返回该站的分类 Tab(推荐 / 全部 / 各题材);
  • 封面:在 app_cover_metadata.go 登记封面相对路径补全规则(站源常返回 //cdn.xxx/img/1.jpg 这类相对地址,需拼上站点前缀)。

四、运行时登记:Config、分派与空页放行

4.1 Config 加字段

app_runtime.go 的 Config 为每个站源保留了 URL 覆盖字段(如 YeguoURL、YeguoAPIURL),让用户在设置里改站源地址。新站源同样加一对字段,默认值走 providerBaseURL 反查。

4.2 目录 / 详情分派

  • 目录:在 nativeCatalog 的分派 加 case sourceXxx: items, result.HasMore, err = d.fetchXxxCatalogPage(...);
  • 详情:在 nativeDetail 的分派 加 case sourceXxx: raw, chapters, err = engine.downloader.fetchXxxDetail(...)。

别忘了空页放行:第一页空结果时哪些站源算"正常"、哪些要报"站源暂未返回剧集",需要把新站源加入对应判断,避免误报错误。

4.3 Dart 侧登记

最后在 lib/models.dart 的 SourceSite 常量列表中登记新站(id 必须与 Go 侧 sourceXxx 完全一致),并确认:

  • 支持在线搜索的站源要把 id 加进 pagedSearch;
  • 真果鉴专属站源放进 restrictedValues(红果鉴单站版不会出现)。

界面(发现页站源切换、搜索、设置开关)都会从这个列表自动生成,无需改页面代码。

五、构建与验证:跑起来才叫完成

按 DEVELOPMENT.md 的调试流程:

python3 scripts/build_native.py --platform android --abi arm64-v8a
flutter pub get --enforce-lockfile
flutter run

验证新站源的推荐路径:

  1. cd native && go test -race ./... 先跑核心测试(测试覆盖见 test/ 与 native/core/*_test.go);
  2. 运行后在发现页切到该站源:分类 Tab、下拉刷新、上滑加载更多是否正常;
  3. 搜索页输入关键词(若支持在线搜索);
  4. 进入详情:封面、集数、续播定位;
  5. 播放第 1 集和第 2 集,确认切集不重新拉详情、倍速与清晰度生效;
  6. 真果鉴(全站源版)调试时 build_native.py 加 --all-sources,再 flutter run --dart-define=ALL_SOURCES=true——版本是编译期开关,Dart 与 Go 两侧必须一致,应用启动时会校验。

六、常见坑位速查 🧭

坑 说明
RE2 不支持 lookahead 多线路解析改用显式字符串截断,别用 (?=...)
来源 ID 不一致 Dart 的 SourceSite.id、Go 的 sourceXxx、canonicalProviderSource 三处必须完全对齐
封面相对路径 忘记在 app_cover_metadata.go 补站点前缀,封面全 404
空页误报 新站源没加入"空页放行"名单,第一页空就弹错
分集重复 / 广告集 详情阶段要去重、跳 is_adv 类广告集,并校验返回与请求一致
忘记 host 反查 provider_media.go 不登记域名,用户自定义地址 / 防盗链 Referer 会失配

七、小结

为红果鉴写视频站源的本质,就是按"常量登记 → 三段式解析(目录 / 详情 / 播放)→ 运行时分派 → Dart 登记"四步,把一个新站源接进 Go 原生核心。参考仓库里"野果"(provider_yeguo.go)或"帝果"这类结构清晰的实现,先跑通目录再补详情和播放,配合 go test 与真机调试,一个可用的新站源通常并不难落地。动手前再扫一眼 DEVELOPMENT.md 的站源开发约定,能帮你避开所有已知的大坑。

登录后查看全文
guoapp