N_m3u8DL-RE完整指南：一条命令跑通 M3U8/MPD/ISM 流媒体下载-开发者社区

N_m3u8DL-RE完整指南：一条命令跑通 M3U8/MPD/ISM 流媒体下载

【免费下载链接】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（MSS）三种清单格式，覆盖点播与直播两类场景。它把"解析清单 → 选流 → 分片下载 → 解密 → 合并混流"整条链路打包在一套命令里，适合会用命令行、手里有流地址（或密钥）的个人用户和运维场景。

下载前的自检清单

先花一分钟确认环境，能避开后面 80% 的报错：

可执行文件：从 Release 页拿到对应平台（Windows / Linux / macOS）的压缩包，解压即得N_m3u8DL-RE可执行文件；Windows 老系统自带终端若显示异常，可换用第三方终端运行
网络可达：浏览器能打开清单 URL 不代表命令行能访问，若内容站需要登录，先准备好 Cookie 或请求头
依赖工具：合并与混流依赖 FFmpeg（自动查找或--ffmpeg-binary-path指定路径）；解密默认调用 mp4decrypt，备选 ffmpeg、shaka-packager
环境体检：运行N_m3u8DL-RE doctor，它会逐项检查系统、运行时和各依赖工具是否就位，加--json可输出结构化结果供排查

一条命令跑通完整下载

以一条公开的 HLS 点播流为例（仓库的 TestStreams.md 里列了一批可直接用的测试流）：

N_m3u8DL-RE "https://example.com/video.m3u8" --auto-select --save-name 我的视频

这条命令依次做了四件事：解析主播放列表并按"每类轨道最佳"自动选流，多线程并发拉取所有分片，将分片合并为完整文件，最后把结果保存到当前目录（文件名由--save-name指定）。跑完你会得到一个可直接播放的文件，旁边还有一份解析结果的 json。

如果不想自动选流，也可以交互确认：去掉--auto-select，程序会列出轨道让你挑选；多段点播内容（如含广告段）默认还会弹出选段界面，空格勾选、回车确认。

场景配方库

按"想下载什么"取用，参数可直接替换。

普通点播：只挑我要的分辨率和音轨

目标：拿到 4K 视频 + 中文音轨，输出 mp4。

N_m3u8DL-RE "URL" \ -sv res="3840*":for=best \ -sa lang=zh:for=best \ -M format=mp4 --save-name 4K视频

-sv/-sa/-ss支持正则匹配分辨率（res）、语言（lang）、编码（codecs）、码率（bwMin/bwMax）等维度，for=best取最优一条，for=all全保留。完整写法可运行N_m3u8DL-RE --morehelp select-video查看。

加密内容：给对密钥，选对引擎

目标：下载 AES-128 加密的 HLS 或带 KID 的 DASH 流。

N_m3u8DL-RE "加密URL" \ --key "KID十六进制:KEY十六进制" \ --save-name 解密后的视频

关键点有三：

所有 KEY 相同时可直接--key KEY；多路密钥用多个--key或--key-text-file文件提供
引擎用--decryption-engine切换，取值MP4DECRYPT（默认）/FFMPEG/SHAKA_PACKAGER，CHACHA20 类建议走FFMPEG
清单里没有写明密钥来源（如 JS 里动态解）时，可用--custom-hls-method+--custom-hls-key+--custom-hls-iv手动指定加密方式与密钥，--custom-hls-scope VIDEO限定只作用于视频流

密钥的提取不在本工具范围内，需要从网页请求或 JS 逻辑里自己拿到，这是新手最常卡住的一步。

直播录制：限定时长，实时合并

目标：把直播内容录 2 小时，边录边合成完整文件。

N_m3u8DL-RE "直播URL" \ --live-real-time-merge \ --live-record-limit 02:00:00 \ --save-name 直播录制

--live-record-limit到点自动停止；不加录制时长则一直录到手动中断。--live-wait-time 30可手动设置清单刷新间隔（秒），网络波动大的线路可调大；--live-idle-timeout用于"连续多少秒没有新分片就自动停"，适合录固定节目单。

直播回看：从历史时间点补录

目标：补录一小时前开始的节目里的 30 分钟。

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

--live-catchup支持回看时长或日期时间两种写法。前提是清单提供可靠的时间戳，且起点仍在服务端回看窗口内，否则回看会失败——这不是参数问题，是源站窗口的问题。

仅字幕：不下载音视频

目标：只抓取全部中文字幕，输出 SRT。

N_m3u8DL-RE "URL" --sub-only --ss name="中文":for=all --sub-format SRT

--sub-only关闭音视频轨道，--sub-format支持 SRT 与 VTT。若还想把字幕混进已有的视频文件，用工具命令N_m3u8DL-RE mux -i video.mp4 -i subtitle.srt -o output.mp4，字幕时间轴默认自动修正。

部分下载：只要某段时间

目标：只下 5 分钟到 20 分钟的内容（分片级保留，不精确裁切）。

N_m3u8DL-RE "URL" --custom-range 05:00-20:00

也可用分片序号（如--custom-range 10-从第 10 片开始）。多段点播里想排除广告段，先--vod-list-parts查看各段编号，再--vod-drop-parts 0,2-4排除。

调优杠杆

参数很多，但真正影响效率的只有下面几个，其余保持默认即可。

入门必改

参数	作用	建议
`--thread-count`（默认 10）	下载线程数	高延迟小分片可调到 16–32；本地网络无收益
`-mt`	音视频字幕并发下载	多轨道（多音轨+字幕）时必开
`--save-dir`/`--save-name`	输出位置与命名	养成固定输出目录习惯，避免污染工作区

进阶可选

参数	作用	何时改
`-R`	限速，如`-R 20M`	怕打满带宽或被源站限流时
`--download-retry-count`（默认 7）	单分片失败重试次数	网络不稳时调大
`--http-request-timeout`（默认 100 秒）	单次请求超时	弱网环境调大；注意分片直播指定后也用作连续无数据超时
`--binary-merge`	二进制合并代替 FFmpeg 合并	分片极多或 FFmpeg 合并报文件句柄问题时，无需 FFmpeg 直接拼

另外，重复用的参数组合可以写进配置文件（Linux/macOS 在~/.config/N_m3u8DL-RE/config.conf，Windows 在%APPDATA%\N_m3u8DL-RE\config.conf），沿用命令行语法，优先级为命令行 > 配置文件 > 内置默认值，省去每次敲长命令的麻烦。

故障定位地图

按现象对号入座，多数问题走前两条就能解决。

清单 403 / 401，或报"无法解析"最可能是缺 Cookie、Referer 或 User-Agent。用-H "Cookie: ..."手动补请求头，或从浏览器导出 Netscape 格式 Cookie 文件后用--cookies cookies.txt载入；确认过 URL 是否有时效参数过期，需--append-url-params把查询参数透传给分片。

下载成功但播放花屏 / 无声解密没做对。核对--key的十六进制完整性（KEY 应为 32 位、KID 为 32 位），换--decryption-engine FFMPEG重试；仍失败就先用doctor确认解密工具在位、版本可用。

分片反复失败、整体极慢先--doctor之外看网络：换--custom-proxy或--use-system-proxy false排除代理干扰，调大--download-retry-count，必要时-R限速绕过源站限流。直播场景下临时断流属于正常，重试耗尽后仍会等待恢复，不必中途杀掉进程。

FFmpeg 相关报错（找不到、合并失败）--ffmpeg-binary-path "完整路径"显式指定；分片数量巨大导致句柄报错时改--binary-merge，或确认默认--ffmpeg-concat-mode LOCAL_HTTP生效（该模式通过本机回环输入逐个打开分片，不吃文件句柄上限）。

直播录着录着停了 / 一直没内容调大--live-wait-time放宽刷新节奏；确认--live-catchup起点没有超出服务端回看窗口；节目结束类断流属预期行为，需要--live-idle-timeout控制自动停止。

能力边界与下一步

三件事它不擅长，提前知道能省时间：一是不抓取网页，输入必须是清单 URL 或本地清单文件，网页解析和密钥提取需要你自己完成；二是不做 Widevine / FairPlay 类 DRM 解密，只处理清单可见的 AES-128、CHACHA20、CENC 等密钥型加密；三是直播回看依赖源站窗口，窗口外无法回补。

下一步建议：