N_m3u8DL-RE 下载器实战：3 条命令跑通，参数怎么挑，问题怎么查-酒店常州论坛

N_m3u8DL-RE 下载器实战：3 条命令跑通，参数怎么挑，问题怎么查

【免费下载链接】N_m3u8DL-RECross-Platform, modern and powerful stream downloader for MPD/M3U8/ISM. English/简体中文/繁體中文.项目地址: https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE

N_m3u8DL-RE 是跨平台流媒体下载器，处理 MPD/M3U8/ISM 清单，点播下载与直播录制都能做。本文按三步走：跑通第一次，按任务挑参数，出问题时按症状定位。

拿到程序，用 3 条命令验证它真的能跑

第一步：拿到可执行文件。两种方式：

# 克隆源码后构建（仓库为只读，产物输出到构建目录） git clone https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE

或者直接使用官方发布渠道对应平台的发行版，省去构建环节。

第二步：跑通最小命令。一个链接加一个文件名就是完整任务：

N_m3u8DL-RE "https://示例点播m3u8链接" --save-name 测试视频

为什么加--save-name：不指定时文件名是自动生成的任务 ID，加它 → 输出文件叫测试视频，验证和找文件都方便。

第三步：用项目自带测试流冒烟。仓库里有一份 TestStreams.md，列出公开测试流。第一个media.axprod.net的Manifest_1080p.mpd带多音轨多字幕，最适合作冒烟对象。先只解析不下载：

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd" --skip-download

--skip-download只走解析 → 终端打印出全部视频档位、音频语言轨、字幕清单。看到轨道列表说明解析链是通的。

再完整跑一遍（去掉--skip-download），文件落盘且能播放 → 安装验证通过。顺手执行一条环境自检：

N_m3u8DL-RE doctor

它会检查 .NET 运行时与 ffmpeg、mp4decrypt 等外部依赖是否就位，缺什么一目了然。验证标准就两条：轨道能列全，成品能播放。

能干什么，哪里会卡：能力清单与如实的限制

它做的事：

点播下载：解析 MPD/M3U8/ISM 清单，拆分视频、音频、字幕轨道，分片并发拉取后合并成片 → 离线存档课程、影视。
直播录制：DASH/HLS 直播流边下边合并，--live-record-limit限制时长，--live-catchup还能从历史时间点回看。
轨道精挑：-sv/-sa/-ss用正则按分辨率、编码、语言、码率、时长过滤，不用手动拼变体链接。
加密内容：内置 AES/ChaCha20 解密，--key喂外部密钥，也可调用 mp4decrypt / shaka-packager / ffmpeg 完成 MP4 分片解密。
字幕转换：--sub-format输出 SRT 或 VTT（默认 SRT）。
附带工具命令：concat（字节拼接）、merge、mux可单独使用，比如补混一条漏下的字幕。

如实说限制：

--live-pipe-mux（管道+ffmpeg 实时混流）⚠️ 网络不稳时容易丢分片，官方明确提示不稳定环境别开，默认关闭也是这个原因。
部分平台有反爬，清单请求缺 Cookie 或 UA 会直接失败 → 需-H手动补请求头或--cookies喂 Cookie 文件。
带密钥的 MP4 分片下载下来仍是密文，必须配--key选对解密引擎才能播放；二进制合并（--binary-merge）拼出的密文文件同样不可播。
混流到 mp4/mkv 依赖系统里找得到的 ffmpeg（或 mkvmerge），找不到会报错。

运行环境：Windows / Linux / macOS，代码基于 .NET（目标 net10.0），需装对应 .NET 运行时；混流与解密才额外依赖 ffmpeg / mkvmerge / mp4decrypt 等工具。常用选项可存进配置文件（Linux/macOS 为~/.config/N_m3u8DL-RE/config.conf，Windows 为%APPDATA%\N_m3u8DL-RE\config.conf），优先级：命令行 > 配置文件 > 内置默认值。

参数按任务选：五组速查

不做大而全的总表，按你手里的任务分组。每个参数 = 何时用 + 为什么用它。

挑流：视频、音轨、字幕怎么选

参数	何时用	为什么
`--auto-select`	变体轨道多、不想逐条挑	自动为视频/音频/字幕各选最佳，一步到位
`-sv res="3840*":codecs=hvc1:for=best`	要精确挑某档画质	正则组合分辨率+编码；`for=best`表示匹配后取码率最高的一条
`-sa lang=en:for=best`	多语言流只要指定语言	按语言代码匹配；`for=best2`可取最好的 2 条
`-ss name="中文":for=all`	只要中文字幕	按名称正则匹配；`--sub-only`则只下字幕
`-dv period="ad":for=all`	清单里混有广告 Period	直接剔除匹配流，比`--ad-keyword`更省事
`--ad-keyword <正则>`	广告分片 URL 有固定关键字	按 URL 关键字过滤分片
`--custom-range 05:00-20:00`	只要某时间段内容	按分片起始时间筛选，保留完整分片不裁切
`--vod-select-parts`/`--vod-list-parts`/`--vod-drop-parts`	多段点播交互选段	强制/关闭交互式选段；脚本场景先列编号再按编号排除

完整正则维度（id、lang、res、codecs、frame、bwMin、plistDurMin、role等）在程序内看：

N_m3u8DL-RE --morehelp select-video

控制输出：落盘、命名与混流

参数	何时用	为什么
`--save-dir <目录>`/`--save-name <名>`	指定输出位置与文件名主干	不指定则文件名是任务 ID、落在当前目录
`--save-pattern "<SaveName>_<Resolution>"`	一次下多个同类型流	模板变量按轨道分辨率等区分命名，避免撞名
`-M format=mp4`	要一个能直接播的成品	下载完把分离的音视频混流进 mp4；`format=mkv:muxer=mkvmerge`换 mkvmerge
`--sub-format SRT`	字幕给播放器用	默认就是 SRT，只有要 VTT 时才需要显式指定
`-mt`	音、视频、字幕都下	三轨并发下载，省总时长
`--skip-merge`	只要原始分片	跳过合并，交给后续`merge`/`concat`处理
`--mux-import "path=zh.srt:lang=chi"`	补下自制字幕或额外音轨	混流时引入外部文件；依赖`-M`开启混流，两者必须同现

网络与代理：慢、卡、走代理

参数	何时用	为什么
`--thread-count 16`	并发不够、下载偏慢	默认 10；显式调高先试这一项
`--http-request-timeout 120`	弱网频繁超时重试	默认 100 秒；直播分片场景未指定时会自动调整，指定后固定
`--download-retry-count 10`	分片失败率高	单分片异常重试次数，默认 7；直播临时断流耗尽重试后仍会等待恢复
`-R 15M`	要限速	单位 Mbps 或 Kbps，如`15M`、`100K`
`--custom-proxy http://127.0.0.1:8888`	必须走指定代理	默认用系统代理（`--use-system-proxy`默认开启）
`--interface eth1`	多网卡要固定出口	按网卡名或本机 IP 绑定，绑定失败直接报错不回退
`--cookies cookies.txt`	平台要登录态	读浏览器导出的 Netscape 格式 Cookie 文件，对清单/密钥/分片全生效
`-H "Cookie: ..."`	手动塞请求头	同时设置时优先于 Cookie 文件，适合单个头精确控制

密钥与解密：加密流怎么喂钥匙

参数	何时用	为什么
`--key "KID:KEY"`	清单只给 KID、KEY 在别处拿到	多组密钥就重复传参；整个流共用一个 KEY 时可只传`--key KEY`
`--key-text-file keys.txt`	密钥很多	从文件按 KID 查 KEY，避免命令行超长
`--decryption-engine FFMPEG`	默认引擎解不开	可选 FFMPEG / MP4DECRYPT（默认）/ SHAKA_PACKAGER，FFMPEG 覆盖面最宽
`--decryption-binary-path C:\Tools\mp4decrypt.exe`	第三方工具不在 PATH	给全路径，免去 PATH 折腾
`--mp4-real-time-decryption`	MP4 分片想边下边解	缩短总时长，不用等全部下完再批量解密
`--custom-hls-method AES_128`+`--custom-hls-key`/`--custom-hls-iv`	HLS 加密方式被误判	手动指定加密方式并直接喂 KEY/IV（支持文件、HEX、Base64）

诊断与直播控制

参数	何时用	为什么
`--skip-download`	只验证解析	列全轨道不下载，冒烟与排错第一步
`--log-level DEBUG`	轨道选不中、结果不对	默认 INFO；DEBUG 输出能看清解析阶段列出的轨道与实际选中项
`N_m3u8DL-RE doctor`	怀疑环境缺件	检查运行时与 ffmpeg、mp4decrypt 等外部工具版本
`--live-record-limit 03:00:00`	直播录满即停	格式`HH:mm:ss`，不用人肉守着中断
`--live-real-time-merge`	直播边录边成型	分片实时合并进成品，中断也能拿到已合并部分
`--live-keep-segments`	开实时合并又怕丢数据	默认 true；保留分片 → 丢数据后还能重拼
`--live-catchup "01:00:00"`	从一小时前回看	也支持日期时间格式；需清单时间信息可靠且起点在回看窗口内
`--live-idle-timeout 120`	直播中断流后不想无限等	列表连续指定秒数无新分片即停（默认关闭）
`--live-perform-as-vod`	把直播当点播下	适合"整场回放"式抓取

任务配方：三个高频场景直接抄

配方一：课程存档，只要最高画质一个 mp4

目标：变体里 720p/1080p 一堆档，只要最高那档，成品能直接播。

N_m3u8DL-RE "课程m3u8链接" --save-name Python实战课程 --auto-select -M format=mp4

--auto-select：如果你懒得逐轨挑 → 它对所有类型自动选最佳，比手写-sv res=...正则不容易漏掉音轨和字幕。
-M format=mp4：为什么加它 → 不加会分别落盘视频、音频、字幕文件，加了才是一次混流成可双击播放的成品。
--save-name：只定文件名主干，避免拿到一串随机任务 ID。
同系列要下多个分辨率：追加--save-pattern "<SaveName>_<Resolution>"，输出变成Python实战课程_1920x1080.mp4，互不撞名。

配方二：直播定时录制 📺

目标：录满 3 小时自动停，文件边下边成型，中断也不丢已录部分。

N_m3u8DL-RE "直播链接" --save-name 技术大会 --live-real-time-merge --live-record-limit 03:00:00 --thread-count 8

--live-record-limit 03:00:00：如果你不想守着 Ctrl+C → 时长到点自动结束，格式HH:mm:ss。
--live-real-time-merge：为什么开它 → 直播分片间隔短、持续滚入，实时合并意味着中断后已合并部分照样可看；不开则全部下完才成型。
--thread-count 8：直播并发不必拉满，8 个足够跟上分片产出，还留带宽给实时合并写入。
网络不稳：保持默认的--live-keep-segments（true），分片留底可重拼；别开--live-pipe-mux，管道数据由 ffmpeg 直接读，丢分片风险更高。

配方三：加密流 + 密钥 + 字幕转换

目标：清单里只有 KID，KEY 已从别处拿到；同时要最高画质和 SRT 字幕。

N_m3u8DL-RE "加密流链接" --key "KID值:KEY值" -sv best -sa best --sub-format SRT

--key "KID:KEY"：密钥格式就是KID1:KEY1，多组密钥重复传参（--key KID1:KEY1 --key KID2:KEY2）；整个流共用一个 KEY 时直接--key KEY。
-sv best/-sa best：加密流档位往往不少，如果你不确定编码名 →best直接取码率最佳，比手搓res=正则省事；要精确时再上-sv res="3840*":codecs=hvc1:for=best。
--sub-format SRT：加密流常带 VTT 字幕，转 SRT 后几乎所有播放器直接识别（默认值本就是 SRT，此参数在配方里是显式声明）。
解密仍报错 → 换引擎--decryption-engine FFMPEG，排查思路见下一节。

附：回看录制

N_m3u8DL-RE "直播URL" --live-catchup "01:00:00" --live-record-limit "00:30:00" --live-real-time-merge -M mkv

从一小时前开始、录 30 分钟、混流为 mkv。--live-catchup覆盖首次取片数量，需要清单时间信息可靠且起点仍在服务端回看窗口内；边界按完整分片取舍，可能有秒级偏差。

出问题了：按症状分诊，先找最可能的原因

下载卡住或极慢

最可能原因：并发数不够 → 超时/重试参数不适配 → 代理不通。排查顺序照这个走：

先试--thread-count 16（默认 10）→ 线程不足是最常见原因，先排除它。
日志里频繁出现超时重试 →--http-request-timeout调到 120 或更高（默认 100 秒），同时--download-retry-count加预算（默认 7）。
还要走代理的场景 → 确认--custom-proxy指向的代理本身能通；程序默认走系统代理，公司内网尤其先查这一环。

对应环节：分片并发调度在src/N_m3u8DL-RE/DownloadManager/，具体分片拉取在src/N_m3u8DL-RE/Downloader/SimpleDownloader.cs。

解密直接报错

最可能原因：密钥格式不对 → 解密引擎不匹配 → HLS 加密方式被误判。

核对密钥：--key接受KID:KEY或纯KEY，多组逐条传，十六进制值别带0x前缀。
换引擎：--decryption-engine可选FFMPEG、MP4DECRYPT（默认）、SHAKA_PACKAGER，先试FFMPEG；同时确认对应第三方程序在 PATH 中，或用--decryption-binary-path给全路径（如--ffmpeg-binary-path C:\Tools\ffmpeg.exe）。
仍不行且是 HLS 流 → 加密方式可能被误判，用--custom-hls-method（AES_128、CHACHA20、SAMPLE_AES等）手动指定，配--custom-hls-key/--custom-hls-iv直接喂密钥材料。

对应环节：解密实现在src/N_m3u8DL-RE/Crypto/（AES、ChaCha20），密钥二次请求在src/N_m3u8DL-RE.Parser/Processor/。

输出文件缺音缺画

最可能原因：轨道没选中 → 混流没开。

跑一遍--log-level DEBUG，对比解析阶段列出的轨道和你实际选中的 → 多数情况是选择器写漏或正则没匹配上。
音画分离且想合 → 补-M format=mp4或-M format=mkv:muxer=mkvmerge。
要引外部字幕/音轨（自制中文字幕、DTS 音轨）→--mux-import path=zh.srt:lang=chi，注意它依赖-M开启混流，两者必须同时出现，缺一个程序直接报错。
字幕时间轴对不上 → 先看--auto-subtitle-fix（默认开启）是否被关掉，或在播放器端再校。

对应环节：解析列轨道在src/N_m3u8DL-RE.Parser/，合并混流在src/N_m3u8DL-RE/Util/（MergeUtil.cs等）。

平台特有坑

旧版 Windows（NT 6.0 及以下）自带终端可能跑不动本程序 → 替代方案：在 cmder 里执行。
macOS 上"找不到命令" → 大概率是没装 .NET 运行时，先装运行时，程序本体才能被命令行找到。
Arch Linux 系可从 AUR 装n-m3u8dl-re-bin（发行版）或n-m3u8dl-re-git（开发版）。
Linux 按网卡名绑定（--interface）可能需要额外权限，报错会带系统原因，不会静默回退。
终端颜色显示异常 →--no-ansi-color关闭彩色输出，不影响功能。

下一步与合规边界

三步走起来：先用 TestStreams.md 里的公开测试流加--skip-download跑通解析 → 对真实链接执行最小化下载确认合并正常 → 把常用参数按场景存成自己的速查组合（可直接写进配置文件，优先级命令行 > 配置 > 默认值）。

合规说明：本项目基于 MIT License 开源，仅限学习和技术研究使用；请只下载你拥有合法权限的内容，遵守所在国家或地区的法律法规与平台服务条款，侵权用途的责任由使用者自行承担。

想读源码，从两个入口进：解析链看 src/N_m3u8DL-RE.Parser/StreamExtractor.cs；参数到运行配置的映射看 src/N_m3u8DL-RE/Config/。功能回归可参考 src/N_m3u8DL-RE.Tests/ 里的解析器与下载管理器测试。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析