Streamlink 版本演进全景:从 0.0.1 到 8.6 的核心变更、安全修复与迁移要点
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:分段流内部重构,引入基础
Segmentdataclass,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.webbrowserAPI 首次登场,用于调用系统 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)。
在仓库中如何查阅与验证
若要进一步核对版本记录中的任何条目,当前仓库提供了完整的落点:
- 版本与变更记录:docs/changelog.md(本文依据)。
- 迁移与弃用说明:docs/migrations.rst、docs/deprecations.rst。
- CLI 参数细节:docs/cli/ 目录(配置、元数据、协议、代理、教程等)。
- 核心流实现:src/streamlink/stream/hls/、src/streamlink/stream/dash/、src/streamlink/stream/segmented/。
- 会话与选项:src/streamlink/session/options.py、src/streamlink/session/http.py。
- 插件清单:src/streamlink/plugins/ 及对应测试 tests/plugins/。
- 验证 API:src/streamlink/validate/。
- webbrowser/CDP:src/streamlink/webbrowser/cdp/client.py。
从安装与使用角度看,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 源码时快速定位每个设计决策的历史动机。