如何为红果鉴编写视频站源:从零接入一个新源的实战教程
如何为红果鉴编写视频站源:从零接入一个新源的实战教程
红果鉴 / 真果鉴是一款 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):
- 校验页码、分类、关键词等入参,非法直接返回错误;
- 调用接口(搜索走
/api/search/result,分类走/api/theater/exploreList),拿到 JSON 数组; - 逐行转成
Drama结构体,ID统一用providerDramaID(source, id)拼成站源:源站ID形式; - 用
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 展示了完整套路:
- 从
Chapter.ID反解出剧集 ID 和集 ID; - 调用播放接口拿到真正的视频地址(
video_url/video_url_h265); - 校验返回数据与请求一致(防止站源串集);
- 组装
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
验证新站源的推荐路径:
cd native && go test -race ./...先跑核心测试(测试覆盖见 test/ 与native/core/*_test.go);- 运行后在发现页切到该站源:分类 Tab、下拉刷新、上滑加载更多是否正常;
- 搜索页输入关键词(若支持在线搜索);
- 进入详情:封面、集数、续播定位;
- 播放第 1 集和第 2 集,确认切集不重新拉详情、倍速与清晰度生效;
- 真果鉴(全站源版)调试时
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 的站源开发约定,能帮你避开所有已知的大坑。
