N_m3u8DL-RE 完整上手指南：M3U8/MPD 下载、解密与直播录制实战
【免费下载链接】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 是一款跨平台的流媒体下载工具，专门解决 M3U8（HLS）、MPD（DASH）、ISM 这类链接"下载下来是一堆散装分片、加密内容打不开、直播录不全"的问题。它把抓取、分片下载、合并、混流、解密整条链路都包办了，你只需要在命令行里给一个链接加几个参数。全文按任务推进：先把工具跑起来，然后拿下第一个视频，再处理带加密的内容，最后完整盯住一场直播。
先想清楚你要干嘛
不同任务读不同的段落，可以先对号入座：
- 还没装好工具 → 从「把工具跑起来」开始，这一步只需要 5 分钟；
- 手里有一个普通链接，想把视频弄下来 → 直接读「拿下第一个视频」；
- 链接下载下来是花的、提示缺密钥、日志里出现 KID/KEY → 读「解密带保护的内容」；
- 想把一场直播从头录到尾 → 读「完整录下直播」；
- 下载到一半报错 → 翻到「踩坑速查」对照处理。
把工具跑起来
这步的目标：让N_m3u8DL-RE在终端里能直接敲出来。它没有复杂的配置项，装二进制文件就行。
在 Windows 上安装它
- 从项目仓库的 Releases 页面下载 Windows 压缩包，解压到任意目录，比如
C:\Tools\N_m3u8DL-RE； - 把这个目录加入系统环境变量
PATH； - 打开新的终端验证：
N_m3u8DL-RE --version能打印出版本号就算装好了。低版本 Windows 自带的终端可能跑不动，官方建议改用 cmder 运行。
在 Linux / macOS 上安装它
下载对应平台的压缩包，解压后给可执行文件加权限并放到PATH里：
# 解压后给可执行文件加执行权限，并移动到系统路径 unzip N_m3u8DL-RE-linux-x64.zip chmod +x N_m3u8DL-RE sudo mv N_m3u8DL-RE /usr/local/bin/Arch Linux 用户也可以走 AUR：yay -Syu n-m3u8dl-re-bin。
装好依赖工具 ffmpeg
下载本身不依赖任何东西，但合并、混流、部分解密都要调用 ffmpeg，建议先装好：
# Ubuntu/Debian sudo apt install ffmpeg # macOS brew install ffmpeg其他两个依赖按需装：mp4decrypt（MP4 解密用）、shaka-packager（个别特殊加密场景用）。装完后跑一句ffmpeg -version，能输出版本信息就 OK。
顺手把界面改成中文（如果默认不是你想要的语言）：
N_m3u8DL-RE "URL" --ui-language zh-CN拿下第一个视频
这章的目标：一个链接进去，一个能播放的文件出来。下面用的示例流来自项目自带的 TestStreams.md，列表里还有几十个可随便练手的链接。
用一条命令下载 M3U8
下载一个 HLS 流，指定输出目录和文件名：
N_m3u8DL-RE "https://storage.googleapis.com/shaka-demo-assets/angel-one-hls/hls.m3u8" \ --save-dir ~/Downloads \ --save-name "angel_test"跑完后看两件事判断成功：日志最后有收尾提示，~/Downloads下出现了angel_test相关文件，拖进播放器能正常播放。
挑对画质和音轨
一个多码率流里可能有好几条视频轨、音频轨，用-sv（视频）、-sa（音频）、-ss（字幕）按正则挑：
# 挑 1080p 最佳视频轨 + 全部音轨 N_m3u8DL-RE "URL" -sv res="1920*":for=best -sa all # 挑最佳中文音轨 N_m3u8DL-RE "URL" -sa lang=zh:for=best # 懒得挑，让程序自动选各类型的最佳轨 N_m3u8DL-RE "URL" --auto-select注意-ss在这里是"选字幕轨"，不是"从某时间点开始下"。想只下载视频的一部分，用的是--custom-range：
# 只下载第 5 分钟到第 20 分钟的内容 N_m3u8DL-RE "URL" --custom-range 05:00-20:00下载完的视频、音频是分开的文件，想要一个能直接播的 MP4，加个混流参数：
# 全部完成后把音视频混流成一个 mp4 N_m3u8DL-RE "URL" -M format=mp4常用参数速查
后面几章也会反复用到这些，集中放在这里：
| 参数 | 作用 | 备注 |
|---|---|---|
--save-dir/--save-name | 输出目录 / 文件名 | 最常用 |
-sv/-sa/-ss | 正则选择视频 / 音频 / 字幕 | 如res="1920*":for=best |
--auto-select | 自动选各类型最佳轨 | 省事首选 |
--thread-count | 下载线程数 | 默认 = 本机 CPU 线程数 |
--download-retry-count | 分片失败重试次数 | 默认 3，弱网可调大 |
--http-request-timeout | 请求超时（秒） | 默认 100 |
--tmp-dir | 临时文件目录 | 磁盘紧张时可指到别的盘 |
-H | 加请求头 | 如-H "Cookie: xxx" |
-mt | 音视频字幕并发下载 | 大文件更快 |
-M | 完成后混流 | 如-M format=mp4 |
--sub-only/--sub-format | 只下字幕 / 字幕格式 | 格式支持SRT或VTT |
--custom-range | 只下部分分片 | 如05:00-20:00 |
哪个参数不确定，敲N_m3u8DL-RE --morehelp 参数名（例如--morehelp select-video）能看详细文档，比翻全量帮助快得多。
解密带保护的内容
这章的目标：把加密流变成能正常播放的明文文件。怎么判断流是加密的？日志里出现EXT-X-KEY、KID 之类的字样，或者下载完播放是雪花屏、音频刺耳，基本就是加密问题。
把密钥喂给程序
密钥有三种给法，看手头材料决定：
# 全流共用一把密钥，直接给 KEY N_m3u8DL-RE "URL" --key "1234567890ABCDEF1234567890ABCDEF" # 不同分片用不同密钥，给 KID:KEY 对（可多次） N_m3u8DL-RE "URL" --key "KID1:KEY1" --key "KID2:KEY2" # 密钥很多时，放一个文本文件，每行一个 KID:KEY N_m3u8DL-RE "URL" --key-text-file keys.txt拿项目自带的加密测试流练手，这条命令可以直接跑：
# 测试流自带 KID:KEY 对，下载即解密 N_m3u8DL-RE "https://media.axprod.net/TestVectors/v7-MultiDRM-SingleKey/Manifest_1080p_ClearKey.mpd" \ --key "9eb4050de44b4802932e27d75083e266:166634c675823c235a4a9446fad52e4d"选对解密引擎
--decryption-engine决定背后调哪个第三方程序，默认MP4DECRYPT，大多数情况不用动：
| 引擎 | 背后程序 | 什么时候用 |
|---|---|---|
MP4DECRYPT（默认） | mp4decrypt | MP4/CENC 类加密的常规场景 |
FFMPEG | ffmpeg | 个别 HLS AES-128 场景 |
SHAKA_PACKAGER | shaka-packager | 前面两个都不行时再试 |
另外两种特殊情况：
- 直播边下边解，加
--mp4-real-time-decryption，MP4 分片下完立刻解密，不用等最后统一处理； - 播放列表里根本没写密钥信息时，手动补：
--custom-hls-method AES_128 --custom-hls-key <HEX或Base64>，方法还可以是CENC、CHACHA20、SAMPLE_AES等，具体值看--help里的枚举。
确认解密结果能播
两招：
# 无输出 = 文件结构没问题 ffmpeg -v error -i output.mp4 -f null -再快进快退把文件头尾各看几眼。如果解密还是失败，九成是密钥本身的问题——KID 和 KEY 没对上，或者 HEX 和 Base64 搞混了，先回头核对密钥格式，再考虑换引擎。
完整录下直播
这章的目标：从开播到收播，得到一个完整可播的直播文件。直播和点播最大的区别是播放列表一直在变，所以要开"直播模式"。
基础直播录制命令
# 开启实时合并：分片边下边拼，Ctrl+C 结束录制并自动完成收尾 N_m3u8DL-RE "LIVE_URL" --live-real-time-merge --save-name "live_recording"判断成功的标准：录制过程中日志持续有新分片写入，Ctrl+C停止后输出文件能正常播放、时长和你实际录的时间基本一致。
项目测试流里有一条 DASH 直播流可以拿来练手（见 TestStreams.md）：
N_m3u8DL-RE "https://cmafref.akamaized.net/cmaf/live-ull/2006350/akambr/out.mpd" \ --live-real-time-merge --save-name "live_demo"限定录制时长
不想盯着终端时，给它一个时长上限，到点自动停：
# 录满 2 小时 30 分钟自动结束（时:分:秒） N_m3u8DL-RE "LIVE_URL" --live-real-time-merge --live-record-limit 2:30:00弱网环境下再加大重试和列表刷新间隔，减少断流丢片段：
# 断流后多等一会儿、多试几次 N_m3u8DL-RE "LIVE_URL" --live-real-time-merge \ --live-wait-time 30 --download-retry-count 10用管道实时混流
--live-pipe-mux会把分片通过管道交给 ffmpeg 实时混成 TS 文件，成品更接近"边录边成片"。在 Linux/macOS 上还可以用环境变量微调 ffmpeg 参数：
# 管道混流时让 ffmpeg 用 copy 视频、AAC 编码音频 export RE_LIVE_PIPE_OPTIONS="-c:v copy -c:a aac -b:a 192k" N_m3u8DL-RE "LIVE_URL" --live-real-time-merge --live-pipe-mux一句提醒：网络不稳定的时候别开管道混流，管道里的数据读取由 ffmpeg 负责，掉流时容易直接丢数据，普通实时合并更稳。另外默认会保留已录分片（--live-keep-segments），方便断了重录，磁盘紧张记得预留空间。
踩坑速查
| 症状 | 大概率原因 | 怎么解决 |
|---|---|---|
| 分片报 401/403、下载 0 字节 | 站点要求身份校验 | -H "Cookie: xxx"补请求头，或--custom-proxy走代理 |
| 提示找不到密钥 / 解密后是雪花屏 | KID 与 KEY 不匹配，或 HEX/Base64 格式混淆 | 核对密钥；HLS 可用--custom-hls-key强制指定 |
| 合并阶段报找不到 ffmpeg | 没装 ffmpeg 或不在 PATH | 装 ffmpeg，或--ffmpeg-binary-path指全路径 |
| 直播录制中间缺片段 | 网络抖动、分片拉取失败 | 调大--download-retry-count，调整--live-wait-time |
| 成品没有声音 | 音轨分离但没选 | -sa all或-sa lang=xx把音轨选上 |
| 直播字幕时间轴对不上 | 字幕起始时间未修正 | 加--live-fix-vtt-by-audio |
| 低版本 Windows 终端报错 | 旧终端不兼容 | 换 cmder 运行 |
| 字幕想只要某一种语言 | 默认全下了 | --sub-only配合-ss name="中文"精挑 |
接下来还能玩什么
跑通上面四件事之后，可以试试：--mux-import把外部音轨、字幕文件混进成品；--save-pattern "<SaveName>_<Resolution>"让文件名自动带上分辨率；--task-start-at定时让任务在指定时刻开始。任何一个参数拿不准，--morehelp 参数名都是最快的一手文档。
【免费下载链接】N_m3u8DL-RECross-Platform, modern and powerful stream downloader for MPD/M3U8/ISM. English/简体中文/繁體中文.项目地址: https://gitcode.com/GitHub_Trending/nm3/N_m3u8DL-RE
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
