N_m3u8DL-RE 上手教程：三条命令完成 DASH/HLS 下载、加密流解密与直播录制-育师

N_m3u8DL-RE 上手教程：三条命令完成 DASH/HLS 下载、加密流解密与直播录制

【免费下载链接】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 是一个跨平台的流媒体下载工具，能解析 DASH(MPD)、HLS(M3U8)、MSS(ISM) 三类清单，覆盖点播下载、直播录制与 CENC/AES-128/ChaCha20 流媒体解密。读完本教程，你可以独立跑通环境体检、用一条命令产出可播放文件，并处理选轨、解密、直播录制三类日常任务。

用 doctor 先给环境做体检：ffmpeg 就位了吗

先说结论：这个程序本身是一个 .NET 可执行文件，但合并和解密环节要借助外部工具。动手下载前，把这几样备齐：

.NET 10 运行时——或者直接用 Releases 里的自包含包，省去装运行时；从源码构建则需要 .NET 10 SDK，执行dotnet build src/N_m3u8DL-RE.sln即可；
ffmpeg——必需，合并分片和混流的主力；
mp4decrypt——默认解密引擎依赖它（Bento4 项目的一部分）；
mkvmerge、shaka-packager——可选，分别用于 MKV 混流和备用解密引擎。

可执行文件放进 PATH 后，跑一条自检命令，它会逐项探测上述工具的状态：

N_m3u8DL-RE doctor

输出按工具逐行列出：[ok]表示找到且版本正常，[missing]表示未找到，[error]表示找到了但跑不起来；每行还会标注该工具是"必需"还是"可选"，并附版本号和退出码。ffmpeg 是红色状态时优先解决，否则后面所有合并都会卡住。工具查找顺序是"指定路径 > 当前目录 > 程序目录 > PATH"，没进 PATH 的工具也可以用--ffmpeg-binary-path之类参数单独指定。想脚本化处理，加--json可输出结构化报告。

Arch Linux 用户可以直接从 AUR 装现成的包；如果习惯用源码，仓库地址是git clone https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE。

拿到第一个可播放文件：点播 DASH 的最短路径

第一次跑通，我推荐用 TestStreams.md 里的明文测试流，其中 axprod 那条带多音轨和字幕，方便观察程序行为。这条命令的含义是：解析 MPD，自动挑好全部轨道，下载并合并：

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-Clear/Manifest_1080p.mpd" --auto-select --save-name demo

执行后终端会先打印解析出的轨道信息，--auto-select帮你选好最佳视频、各语言最佳音频和字幕，接着是分片下载进度条，全部完成后调用 ffmpeg 自动合并。退出时目录里会多出一个可播放的 mp4 和一份 meta.json（存放解析信息，默认开启，可用--write-meta-json false关掉）。

💡两个高频坑：系统里没装 ffmpeg 时，程序会抛找不到ffmpeg，请自行下载并直接退出——先装 ffmpeg 或加--ffmpeg-binary-path指定完整路径。另外，不指定--save-name时程序会生成带时间戳的长文件名，起好名字后续找文件省心。

实战任务：三个最常用的场景

任务一：点播里只下目标分辨率和语言

目标：从多轨道节目里只取"1920 级最高码率视频 + 英语音频"的组合，4K 流不浪费带宽。

N_m3u8DL-RE "<链接>" -sv res="1920*":for=best -sa lang=en:for=best --save-name 我的视频

参数拆解：

-sv按正则选视频轨：res="1920*"把范围圈到 1920 级别，for=best再取码率最高的一条；
-sa lang=en:for=best拿英语最佳音轨；不写-ss就不下字幕；
for缺省就是best，想全要写for=all，取前两条写for=best2；
同时选多条轨道时加--save-pattern "<SaveName>_<Resolution>_<Language>"生成互不冲突的文件名，模板变量可用--morehelp save-pattern查看。

替代方案：完全不想写正则就挂--auto-select，程序替你做全部选择；反向筛选用-dv/-da/-ds，比如-dv res="^3840x"去掉所有 4K 轨。

坑点：res的格式是"宽x高"，要写1920x1080而不是1920*1080；星号只适合写1920*这种前缀式通配，写错正则时程序会报没有匹配到流。

任务二：一条命令解密加密流

目标：手里已有 KID:KEY 配对，把它喂给程序，拿回解密后可直接播放的文件。

N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd" \ --key 9eb4050de44b4802932e27d75083e266:166634c675823c235a4a9446fad52e4d --save-name decrypt_test

上面这条是 TestStreams.md 里的 ClearKey 样例，KID 和 KEY 都是公开已知的，正好用来演练解密流程。分片下完后程序自动调用解密工具，写出的就是解密后的文件，无需手工后处理。

参数拆解：

--key接KID:KEY配对，全部轨道共用一把密钥时直接--key KEY即可；多 KID 就重复传多条；
解密引擎默认MP4DECRYPT（调 mp4decrypt），PATH 里没有这个工具时程序直接退出；
--decryption-engine FFMPEG改走 ffmpeg 解密，不依赖额外工具；开--mp4-real-time-decryption实时解密时官方建议改用 SHAKA_PACKAGER；
密钥量大时用--key-text-file指向 KID→KEY 映射文件，程序按 KID 自动查找。

替代方案：密钥 URI 写在播放列表里的自包含 HLS AES-128 流，不需要任何--key，比如 TestStreams 中的 oceans_aes.m3u8 可直接下。密钥不在清单里的自定义 HLS 场景，再用--custom-hls-key/--custom-hls-iv指定（HEX、Base64 或文件路径都行）。

⚠️坑点：KID 和 KEY 都支持 16 字节 HEX 或 Base64（Base64 末尾的=可省略）。配对粘错时解密工具会报错，已下载的分片不会自动重来——核对密钥后重跑即可。

任务三：直播按限时长录制并实时合并

目标：让程序守着一个持续开播的流录到指定时长自动收手，直接产出完整文件。

N_m3u8DL-RE "<直播链接>" --live-record-limit 00:30:00 --live-real-time-merge

跑起来后程序持续轮询播放列表拉新分片，录满 30 分钟自行收尾。TestStreams 里的 cmafref 直播 DASH 链接可以拿来直接试。

参数拆解：

--live-record-limit收HH:mm:ss，是录制的总时长上限；
--live-real-time-merge边录边合并，省掉事后二次合并；分片默认仍会保留（--live-keep-segments默认 True），想省盘加false；
首屏回看深度默认取 16 个分片（--live-take-count），想从更早开始改--live-catchup "01:00:00"或具体日期时间，它会覆盖 take-count；
列表长时间没有新分片时可以挂--live-idle-timeout 600自动停录，避免程序空转。

替代方案：--live-pipe-mux走管道 + ffmpeg 实时混出 TS，链路更短；README 明确提示网络不稳时管道易丢数据，我不建议默认开启。

坑点：忘挂时长上限时，录制会一直跑到你手动 Ctrl+C；--live-catchup依赖清单提供可靠的时间信息，且起点必须还在服务端回看窗口内，边界可能略有偏差。

常用参数一览表：12 个覆盖大多数任务

参数	作用	示例值
`--save-name`	输出文件名	`--save-name 电影名`
`--save-dir`	输出目录	`--save-dir "D:\Videos"`
`--save-pattern`	文件名模板，多轨道防冲突	`<SaveName>_<Resolution>_<Language>`
`--thread-count`	下载线程数，默认 10	`--thread-count 16`
`--auto-select`	自动挑最佳视频/音频/字幕	`--auto-select`
`-sv`/`-sa`/`-ss`	正则选视频/音频/字幕	`-sv res="^3840x":codecs=hvc1:for=best`
`--key`	解密密钥，KID:KEY 或纯 KEY	`--key KID1:KEY1`
`--decryption-engine`	解密引擎，默认 MP4DECRYPT	`--decryption-engine FFMPEG`
`-R`	限速，Mbps/Kbps	`-R 15M`
`-M`	完成后混流分离的音视频	`-M format=mp4`
`-H`	追加请求头	`-H "User-Agent: iOS"`
`--live-record-limit`	直播录制时长上限	`--live-record-limit 01:00:00`

这些常用选项还能写进 UTF-8 配置文件（Linux 在~/.config/N_m3u8DL-RE/config.conf，Windows 在%APPDATA%\N_m3u8DL-RE\config.conf），程序启动时自动读取，优先级为命令行 > 配置文件 > 内置默认值，支持#注释和带引号的值。

终端报错时怎么办

找不到ffmpeg，请自行下载且程序直接退出→ ffmpeg 不在 PATH 里 → 安装 ffmpeg 并加入 PATH，或用--ffmpeg-binary-path指向完整路径。
找不到mp4decrypt，请自行下载→ 默认解密引擎 MP4DECRYPT 依赖该工具但系统没有 → 安装 Bento4，或改用--decryption-engine FFMPEG只靠 ffmpeg。
403 或分片反复失败→ 平台校验请求头，或分片 URL 需要携带链接上的参数 → 用-H "..."补上所需请求头；仍失败就加--append-url-params把输入链接的查询参数带到每个分片上。
合并失败，提示 too many open files→ 分片数量触到系统文件句柄上限 → 按提示改用--ffmpeg-concat-mode PROTOCOL重试，或先ulimit -n调高限额。
直播录制缺数据、画面掉帧→ 开了--live-pipe-mux，网络不稳时管道丢帧 → 关掉管道混流，换--live-real-time-merge普通实时合并。
终端进度条、颜色显示错乱→ 旧版 Windows 自带终端不支持 ANSI → 换 cmder 等第三方终端，或加--no-ansi-color去色；反过来，终端明明支持却没被识别时可用--force-ansi-console强制启用。