Streamlink 版本演进全景:从 0.0.1 到 8.6 的核心变更、安全修复与迁移要点

原创2026-09-22 22:22:361,813 阅读
文章标签:音视频

Streamlink 版本演进全景:从 0.0.1 到 8.6 的核心变更、安全修复与迁移要点

导读

本文以 Streamlink 官方版本记录(docs/changelog.md,覆盖 2016 年 0.0.1 至今 8.6.1 的全部版本)为核心骨架,梳理这条 CLI 流媒体工具的十年演进主线:安全漏洞如何被修复、CLI 与 Python API 如何逐步重构、HLS/DASH 分段流实现经历了哪些关键改进、插件系统如何从"一次加载全部"走向懒加载,以及多次大版本中的破坏性变更与迁移路径。读者读完可以建立对 Streamlink 功能脉络的整体认知,并能在当前仓库中找到对应源码与文档作为深入线索。

发布节奏:Patch、Minor 与 Major

从 docs/changelog.md 的记录看,Streamlink 采用语义化版本号,发布节奏基本保持"每月或每季度一个 Minor 版本、按需发布 Patch 版本、每年一两个 Major 版本":

  • Patch 版本(如 8.6.1、8.2.1、7.1.1):只包含修复,不引入新功能,部分 Patch 版本甚至明确标注 "No code changes"(如 5.2.1、4.0.1、1.4.1),仅说明构建或部署脚本调整。
  • Minor 版本(如 8.6.0、7.5.0):聚集新功能、插件更新与内部重构,多数版本会给出 "Release highlights" 摘要,随后是完整的 PR 列表。
  • Major 版本(6.0.0、7.0.0、8.0.0):以 "Breaking changes" 独立成节,集中宣布弃用项的移除与依赖下限提升。

版本记录中的每一项均对应具体 PR 编号,说明每个变更都有完整的实现与测试支撑。仓库中这些功能的测试分布在与源码平行的目录中,例如 tests/stream/hls/test_hls.py、tests/stream/dash/test_dash.py,可作为验证具体行为的入口。

安全修复脉络:重定向与 file:// 协议防护

版本记录中多次出现 "SECURITY" 条目,反映了项目对任意本地文件读取类漏洞的持续加固:

  • 8.6.0(2026-09-13):修复通过 HTTP(S) 重定向到 file:// URL 造成的任意本地文件读取(CVE-2026-92164),同时修复 HTTPS→HTTP 的不安全跨协议重定向。
  • 8.4.0(2026-05-06):修复 HLS 与 DASH 中 file:// URI 导致的任意本地文件读取(CVE-2026-44353)。
  • 8.5.0(2026-08-01):虽然不涉及运行时漏洞,但将 GitHub Releases 设为不可变、将全部 GitHub Actions 固定到 commit ID、并为所有 CI 工作流与发布产物切换到 uv lockfile,属于供应链安全加固。

这类攻击面与 Streamlink 的输入解析模型直接相关:用户提供的 URL 会经过 HLS/DASH 清单解析、分段 URL 拼接等流程,requests_file 适配器(见 src/streamlink/packages/requests_file.py)为文件协议提供了支持基础,因此对 scheme 白名单与重定向处理必须严格校验。CHANGELOG 中未披露漏洞细节,但补丁均指向单一修复 commit,建议升级到受影响版本之上的最新版。

CLI 与会话选项的演进:分段流选项的统一

分段流(HLS/DASH 等)相关的 CLI 参数经历了"协议专属 → 通用"的整合过程,这是版本记录中最清晰的一条参数演进线:

2.4.0:通用选项取代协议专属选项

2.4.0 弃用了 --{dash,hds,hls}-segment-attempts、--{dash,hds,hls}-segment-threads、--{dash,hds,hls}-segment-timeout 与 --{dash,hds,hls,rtmp,http-stream}-timeout,改用:

  • --stream-segment-attempts
  • --stream-segment-threads
  • --stream-segment-timeout
  • --stream-timeout

7.0.0:协议专属选项的正式移除

7.0.0 将 hls-segment-attempts、hls-segment-threads、hls-segment-timeout、hls-timeout、dash-segment-attempts、dash-segment-threads、dash-segment-timeout、dash-timeout、http-stream-timeout 全部移除,迁移细节见 docs/migrations.rst。

8.0.0 / 8.1.0:时长与队列语义的重命名

  • 8.1.0 弃用 --hls-segment-queue-threshold,改为 --stream-segmented-queue-deadline。
  • 8.0.0 新增 --stream-segmented-duration(取代并弃用 --hls-duration),使时长限制统一作用于 HLS、DASH 及其它分段流类型。

在源码中可以看到这两个选项的注册与默认值:src/streamlink/session/options.py 中 stream-segmented-duration 默认 0.0、stream-segmented-queue-deadline 默认 3,同时通过 _factory_set_deprecated 保留了 hls-duration 与 hls-segment-queue-threshold 的别名兼容(对应行:"hls-duration": _factory_set_deprecated("stream-segmented-duration", float) 等)。

其它值得关注的新增参数

版本记录中新增的 CLI 参数覆盖面很广,比较典型的有:

版本 参数 用途
8.4.0 --stream-passthrough-encrypted 将加密的 HLS/DASH 分段不做任何检查直接透传给输出流
8.2.0 --http-cookies-file 从文件加载 HTTP cookies,对应 session 选项 http-cookies-files
8.0.0 --ffmpeg-validation-timeout 延长 FFmpeg 可执行文件校验超时
7.6.0 --skip 输出文件已存在时跳过而非交互式询问
7.5.0 --no-plugin-sideloading / --no-plugin-cache 关闭插件旁路加载与插件缓存文件 I/O
6.10.0 --logformat / --logdateformat / --ffmpeg-loglevel 自定义日志格式与 FFmpeg 日志级别
6.2.0 --player-env 为播放器进程设置环境变量
5.4.0 --progress 取代旧 --force-progress,控制进度显示
5.5.0 --no-config 跳过配置文件读取
5.0.0 --player-external-http-continuous 连续 HTTP 输出模式
3.0.0 --twitch-api-header 仅针对 Twitch API 请求设置头部
2.1.0 --interface / -4 / -6 选择网络接口与 IP 协议族

其中 --stream-passthrough-encrypted 在源码中贯通 session 选项与流实现:默认值注册于 src/streamlink/session/options.py("stream-passthrough-encrypted": False),HLS 流与 DASH 流分别通过 session.options.get("stream-passthrough-encrypted") 读取(见 src/streamlink/stream/hls/hls.py、src/streamlink/stream/dash/dash.py)。而 --http-cookies-file 对应 session 选项列表中的 http-cookies-files(见 src/streamlink/session/options.py 第 93 行文档表),其 setter 负责解析 cookie 文件格式。

流协议实现:HLS 与 DASH 的关键改进

版本记录中 HLS/DASH 相关条目数量庞大,主要可以归纳为几个方向:

HLS

  • 3.0.0:移除 rtmp://、hds://、akamaihd:// 协议插件与全部 Flash 相关代码,HLS 成为事实上的主协议。
  • 2.3.0:实现 HLS 媒体初始化段(fMP4 流)。
  • 8.3.0:HLSStream.parse_variant_playlist() 新增 check_streams="segments" 支持,可进一步探测分段是否可访问。源码中 _check_streams 接受 bool | Literal["playlists", "segments"] 类型并区分两种检查策略(见 src/streamlink/stream/hls/hls.py 第 792 行起)。
  • 8.6.0:新增 HLS packed audio 流支持;新增 HLSSegment.{get,iter}_content() 与 HLSStreamWriter.{get,iter}_segment_content(),允许插件在写盘前修改分段数据(bigo 插件的 MPEG-TS 解密即基于此能力)。
  • 8.0.0:HLS 流在缺少 EXT-X-ENDLIST 时,若轮询两次 targetduration 时长仍无新分段则提前停止(此行为 6.0.0 引入)。
  • 8.5.0:修复流起始偏移被错误转换为 int 的问题;--hls-playlist-reload-time 开始接受浮点数。
  • 8.1.1:--hls-segment-ignore-names 不再硬编码 .ts 后缀。
  • 6.3.0 / 6.4.0:分段流内部重构,引入基础 Segment dataclass,HLS/DASH 子类继承。

DASH

  • 0.13.0:首次加入 MPEG-DASH 支持。
  • 6.4.0:补齐动态 DASH 清单中 SegmentList 的支持;清单重载间跳过分段时输出警告日志。
  • 8.6.0:修复 SegmentTimeline.S 节点 t 属性求值错误;修复 HLS daterange 中零或负时长。
  • 8.2.0:修复动态 DASH 清单轮询时缺少 representation 的处理。
  • 7.1.0:修复动态 DASH 清单错误要求 publishTime / availabilityStartTime 属性、分段与清单 BaseURL 拼接错误、timeline 清单分段时长错误。
  • 8.0.0:dash:// 流(DASHStream)新增 duration 参数;DASHStream.parse_manifest() 新增 with_{video,audio}_only 参数(6.0.0)。
  • 7.1.0:FFmpeg 不可用时不再抛出未捕获错误,而是只返回不参与 mux 的单路视频或音频子流。

流输出与封装

  • 8.6.0:FFMPEGMuxer 新增 itsoffset 选项。源码 src/streamlink/stream/ffmpegmux.py 中通过 self._cmd.extend(["-itsoffset", f"{itsoffset_item}"]) 为每个输入管道设置时间偏移;HLS packed audio 流正是利用该机制为音频子流设置偏移(见 src/streamlink/stream/hls/hls.py 第 697-699 行)。
  • 7.3.0:下载进度改由控制台输出流而非固定 stderr,非交互环境输出状态行。
  • 5.3.0 / 4.2.0:修复 mux 流末尾数据缺失、命名管道清理不及时、FFmpegMuxer 未并发关闭子流等问题。

插件系统演进:从全量加载到懒加载

插件系统是版本记录中变动最频繁的领域:

  • 6.6.0:实现懒插件加载——内置插件在解析输入 URL 时才按需加载,显著缩短启动时间并降低内存占用。同时将 streamlink.session 重构为子包(streamlink.session.http 取代 streamlink.plugin.api.http_session),弃用 Streamlink.{get,load}_plugins()。
  • 2.3.0:实现新的插件 URL 匹配 API(@pluginmatcher),旧 can_handle_url() / priority() 在 6.0.0 被移除。
  • 5.0.0:新增 pluginargument 装饰器;移除 Plugin.bind() 并改变 Plugin 构造器签名(提供临时兼容包装)。
  • 7.1.0:matchers 与 arguments 对象不再在继承的 Plugin 类间共享;7.1.1 修复懒加载下 --show-matchers=pluginname 失效的问题。
  • 7.5.0:插件缓存(key-value store)文件 I/O 得到改进,可分别用 --no-plugin-sideloading、--no-plugin-cache 关闭。
  • 8.0.0:Twitch 新增 --twitch-supported-codecs 参数以访问更高质量流。

插件本身的增删在版本记录中持续进行:例如 8.6.0 移除了 ard_live、piczel,重写了 ard_mediathek、tiktok、vidio、zdf_mediathek;8.0.0 移除 nhkworld;7.0.0 将 afreeca 更名为 soop;更早版本则成批清理下线站点的插件(如 6.11.0 一次性移除 crunchyroll、facebook、mildom 等九个插件)。当前仓库中的插件清单位于 src/streamlink/plugins/,每个插件对应一份 test_*.py 测试(见 tests/plugins/)。

安全与网络层:HTTPSession 与代理

  • 8.5.0:重构 HTTPSession 并修复大量类型问题。
  • 6.8.0:新增 SSLContextAdapter(src/streamlink/session/http.py),为 kick 等插件解决 Cloudflare 类防护提供定制 TLS 上下文的基础。
  • 3.0.0:无 scheme 的输入 URL 默认改用 HTTPS;--https-proxy 弃用,统一由 --http-proxy 同时作用于 HTTP/HTTPS 请求与 websocket 连接。
  • 8.4.0 / 8.3.0:--interface 支持按名称选择网络接口(类 curl 语法,非 Windows 平台),并修复其在会话初始化后挂载的 adapter 上不生效的问题。
  • 6.9.0:新增 streamlink.plugin.api.webbrowser 子包与 aws_waf 模块,用于绕过 AWS WAF 机器人检测(vtvgo 插件使用)。

Python 版本支持与依赖下限

版本记录完整呈现了 Python 支持矩阵的推移:

版本 Python 相关变更
2.0.0 移除 Python 2 与 3.5 支持
4.0.0 移除 Python 3.6
6.0.0 移除 Python 3.7
7.0.0 移除 Python 3.8(Win 7/8 不再受支持)
8.0.0 移除 Python 3.9
6.2.1 / 6.10.0 / 7.6.0 / 8.6.0 官方支持 3.12、3.13、3.14、3.15

依赖方面同样有明确轨迹:urllib3 于 5.1.0 成为直接依赖并在 8.0.0 提升到 >=2.0.0;lxml 在 8.6.0 提升到 >=5.0.0(此前 7.5.0 调整为 >=4.6.4,<7);requests 在 2.3.0 升至 >=2.26.0,<3;pycountry 在 3.0.0 取代 iso-639+iso3166;8.6.0 中 optional 依赖 zstandard 在 Python 3.14+ 被移除。构建侧,4.0.0 从 versioneer 切换至 versioningit,6.0.0 将项目元数据迁入 pyproject.toml(PEP 621),7.5.0 用 PEP 735 依赖组取代 {dev,docs}-requirements.txt,当前构建配置见 pyproject.toml。

大版本破坏性变更与迁移路径

三个 Major 版本的变更范围最大,值得单独梳理:

3.0.0(2021-11-17)

  • 移除 RTMP/HDS/AkamaiHD 协议与全部 Flash 代码,删除 --rtmp-*、--hds-*、--subprocess-* 参数,移除 RTMPDump 依赖。
  • 无 scheme URL 默认 HTTPS。
  • Session.resolve_url() 改为返回 (plugin_class, resolved_url) 元组。
  • 依赖从 iso-639/iso3166 切换到 pycountry。

6.0.0(2023-07-20)

  • 移除 Python 3.7。
  • --player 变为纯路径参数,自定义播放器参数必须走 --player-args;移除 {filename} 变量(改用 {playerinput})。
  • API 层移除 Plugin.can_handle_url() / Plugin.priority()、Streamlink.{g,s}et_plugin_option()、全局插件参数、validate.text。
  • 实验性 streamlink.webbrowser API 首次登场,用于调用系统 Chromium 提取网站数据,Twitch client-integrity token 作为其首批应用。

7.0.0(2024-11-04)

  • 移除 Python 3.8;移除旧配置文件路径与旧插件旁路加载路径。
  • 移除流类型相关 CLI 参数(见上文 2.4.0 弃用列表)。
  • 移除 HTTPSession/HTTPAdapter 与 NoPluginError/NoStreamsError/PluginError/Plugin 的旧导入路径。
  • 全面改用 ruff 格式化与 PEP 563/585/604/613 类型注解。

8.0.0(2025-11-11)

  • 移除 Python 3.9;urllib3 下限升至 2.0;移除 HLSStream/MuxedHLSStream 的 url_master 参数。
  • 新增 --stream-segmented-duration、--ffmpeg-validation-timeout、Flatpak 播放器探测、--twitch-supported-codecs。

每次破坏性变更都在 docs/migrations.rst 与 docs/deprecations.rst 中留有对应说明,升级前应优先查阅这两个文档。

新能力版图:webbrowser、验证 API 与元数据

版本记录中出现的几项"新能力"值得展开说明:

  • webbrowser API(6.0.0 实验性,6.9.0 扩充):CDPClient.session() 在 6.9.0 新增 max_buffer_size 参数;7.6.0 新增 CDPClientSession.{apply,retrieve}_cookies() 用于在 Streamlink 的 HTTP 会话与浏览器之间复制 cookie。源码见 src/streamlink/webbrowser/cdp/client.py,其中 CDPClientSession 封装了网络请求拦截与 JS 求值能力。
  • validate API:6.4.0 起为验证模式(schema)补齐了完整 API 文档;8.6.0 新增 nextjs_inline_rsc() 校验器,用于解析 Next.js 的 RSC 内联数据(实现见 src/streamlink/validate/_validators.py 的 validator_nextjs_inline_rsc)。
  • 元数据变量:2.4.0 为 --output/--record 新增 {author}、{category}/{game}、{title}、{url} 变量与 {time} 变量;4.0.0 新增 plugin 变量;6.2.0 起文档按插件列出受支持的元数据变量。文件输出路径还支持通过元数据变量自动创建父目录(3.0.0),并提供 --fs-safe-rules 自定义非法字符替换规则(2.4.0)。

在仓库中如何查阅与验证

若要进一步核对版本记录中的任何条目,当前仓库提供了完整的落点:

从安装与使用角度看,Streamlink 以 CLI 形式调用:streamlink <URL> 即可解析流,配合 --player、--output、--record 等参数进行播放或录制;通过 python -m streamlink(1.6.0 起支持)也可直接运行。所有未在 changelog 中标注"将移除"的选项均可直接使用,被弃用的选项会在运行时输出 warning 级日志提示迁移方向。

结语

从 2016 年对 Livestreamer 的分叉到 2026 年的 8.6.x,Streamlink 的版本记录本身就是一部浓缩的工程史:流协议从 Flash 时代走向纯 HLS/DASH,网络层持续应对重定向与加密防护挑战,CLI 参数经历两轮"协议专属 → 通用"的统一,插件系统完成懒加载改造,Python 支持矩阵逐年收紧。理解这条演进线,不仅有助于升级时平稳迁移,也能让你在阅读 src/streamlink 源码时快速定位每个设计决策的历史动机。

登录后查看全文
streamlink