从 CPU 软编解码到 GPU 硬编解码，差的不是命令而是配置。这一章讲清楚 NVENC / NVDEC 是怎么被编译进 FFmpeg 的，以及为什么 nv-codec-headers 从 9.1 降到 8.1 才是正确的解法——先调查，再动手
核心方法论：运筹帷幄（先调查，再动手）
「运筹帷幄之中，决胜千里之外。这一章我们不急着敲命令，而是先把战场摸清：你的显卡有没有硬编解码单元？驱动、头文件、FFmpeg 三者的版本能不能对上？把这些变量列全、把每条路的代价算清，再动手编译——素材里那次把 nv-codec-headers 从 9.1 降到 8.1 就成功的翻盘，靠的正是'先调查再动手'，而不是一上来就兴师动众升级驱动。」
第 2 章里我们用 libx264 转码，那是软编解码（software codec）——说人话：让 CPU 的通用计算核去跑 H.264 的压缩算法。软编解码的好处是纯软件、人人可编译、画质控制精细；坏处是 CPU 是通用核，干"压缩视频"这种专用活儿效率并不高——转码时 CPU 几乎占满，速度还常常只有几十帧每秒。服务器上同时转几路视频，CPU 直接被打穿。于是 GPU 厂商在显卡里焊了专用硬件单元：NVIDIA 的 NVENC（编码单元）和 NVDEC（解码单元），只干编解码这一件事，效率远超通用核跑算法，这就是硬编解码（hardware codec）。顺带记一个历史名词：NVDEC 的 API 旧名叫 CUVID，素材里满屏的 cuvid 指的就是它。
那 FFmpeg 为什么需要额外的 nv-codec-headers？因为 NVENC / NVDEC 是 NVIDIA 的私有接口，FFmpeg 作为第三方软件，必须拿到 NVIDIA 的 SDK 头文件（接口声明，说人话就是"这些函数的签名长什么样"），才能在编译时把 h264_nvenc、h264_cuvid 这些编解码器"焊"进自己的二进制。这套头文件由 FFmpeg 官方仓库维护（GitHub 上的 nv-codec-headers），make install 后默认装到 /usr/local/include/ffnvcodec。没有它，configure 阶段就找不到 NVENC 相关符号。先看两条管线在"谁干活"上的本质区别：
# CPU 软编解码管线（第 2 章的默认路径）—— 干活的都是 CPU 通用核
输入文件 --解封装--> 压缩流 --libx264 解码--> 原始帧 --libx264 编码--> 输出文件
# GPU 硬编解码管线（本章目标）—— 解码交给 NVDEC，编码交给 NVENC
输入文件 --解封装--> 压缩流 --NVDEC 解码--> 原始帧 --NVENC 编码--> 输出文件
@NVDEC=显卡里的专用解码单元，NVENC=专用编码单元，CPU 只负责拆箱装箱# nv-codec-headers 的编译安装（官方标准流程；素材记录的是其中的版本选择）
git clone https://github.com/FFmpeg/nv-codec-headers
cd nv-codec-headers
git checkout sdk/8.1 # 版本必须与驱动匹配——7.4 节的主战场
make install # 默认装到 /usr/local/include/ffnvcodec| 维度 | CPU 软编解码 | GPU 硬编解码 |
|---|---|---|
| 干活的人 | CPU 通用核（libx264 / libx265 算法） | 显卡专用单元（NVENC / NVDEC） |
| 速度 | 慢，CPU 满载也常只有几十 fps | 快，数倍到数十倍 |
| CPU 占用 | 高，转码时几乎占满 | 低，编解码都甩给 GPU |
| 画质 | 高，x264 高预设可精细控制 | 稍逊，码率与画质控制粒度粗 |
| 依赖 | 纯软件，人人可编译 | 驱动 + SDK 头文件 + 非自由许可 |
硬编码不是"画质更好"，是"更快、更省 CPU"。直播、批量转码、服务器转码这类场景首选硬编码；追求单路最高压缩画质，仍要回到 CPU 的慢速预设。先想清楚你要什么，再选路——这是运筹帷幄的第一课：目标决定路线，路线决定配置。
诸葛亮用兵前先派斥候。编译 FFmpeg 之前，先回答两个问题：机器上有没有 NVIDIA 显卡？驱动装没装对？第一问用 lspci——说人话，它列出 PCI 总线（主板上的高速设备通道）上的所有设备，grep VGA 把显卡那一行过滤出来。素材实录（2019 年的 CentOS 7 服务器）：
# 素材实录：查看机器上显卡的型号
lspci | grep VGA
# 输出见素材截图：直接列出显卡厂商与型号（NVIDIA 的型号行就在其中）第二问看驱动。素材里驱动来自两个途径：一是从 NVIDIA 官网下载对应显卡的驱动包安装；二是素材的 CUDA 版本是 CUDA 10.0.130——这个版本自带驱动（装完 CUDA 就是驱动 410.48），所以素材原话是"这个版本自带驱动，可以不用安装驱动"。装好后用 nvidia-smi 确认——它是 NVIDIA 的系统管理接口，显示驱动版本、GPU 型号、显存占用、利用率等。素材实录：
# 素材实录：nvidia-smi 查看驱动与显卡状态
nvidia-smi
# 输出见素材截图：Driver Version、CUDA Version、GPU 型号、显存占用、利用率# 素材实录：驱动安装的两个途径（二选一，装好后用 nvidia-smi 验证）
# 途径一：NVIDIA 官网下载对应显卡型号的驱动安装包
https://www.nvidia.com/Download/index.aspx?lang=en-us
# 途径二：安装 CUDA 10.0.130（自带驱动 410.48，可以不用安装驱动）注意：驱动是"地基"。硬编解码器不在 FFmpeg 里，而在驱动固件里——说人话，显卡的编码解码能力由驱动加载的底层固件程序提供，FFmpeg 只是"打电话的人"，驱动版本决定了它能调用的编码器能力上限。这也埋下了 7.4 节版本匹配故事的祸根：头文件声明了驱动固件没有的接口，编译或运行必然出错。
侦察动作越早，返工越少。编译前花两分钟跑 lspci | grep VGA 和 nvidia-smi，把显卡型号和驱动版本记下来——它们就是 7.4 节查版本对应表的输入。没有显卡或驱动没装好，后面 configure 再对也是白忙。
第 5、6 章反复强调过：FFmpeg 的功能在 ./configure 阶段就"焊死"了，之后想加功能只能重新编译。GPU 硬编解码也一样——必须在 configure 时显式声明。素材实录里，作者在 ./configure 时追加了下面这组选项（素材原文，历史命令）：
# 素材实录：./configure 时追加的 GPU 选项（2020 年，FFmpeg n4.1.1 时代）
--enable-cuda-sdk \
--enable-cuvid \
--enable-nvenc \
--enable-nonfree \
--enable-libnpp \
--extra-cflags=-I/usr/local/cuda/include \
--extra-ldflags=-L/usr/local/cuda/lib64每个选项各管一件事。--enable-cuda-sdk：启用 CUDA SDK——注意这是旧版选项名，新版本里已改名为 --enable-cuda-nvcc（改用 nvcc 编译器探测 CUDA）；--enable-cuvid：编译 GPU 解码器（CUVID 是 NVDEC 的旧名），让 FFmpeg 认识 h264_cuvid 这类解码器，新版本另有同族开关 --enable-nvdec；--enable-nvenc：编译 GPU 编码器，让 FFmpeg 认识 h264_nvenc 这类编码器；--enable-nonfree：接受非自由许可——NVENC 的许可证不自由，FFmpeg 默认不编译非自由组件，必须显式声明"我接受"；--enable-libnpp：启用 NVIDIA 的 NPP 图像处理库，GPU 上的缩放滤镜 scale_npp 就是它的产物；--extra-cflags / --extra-ldflags：告诉编译器和链接器去 /usr/local/cuda 找头文件与库。今天的官方文档（FFmpeg 6.x / 7.x）要求的 NVIDIA 选项集合如下：
# 现行版本（FFmpeg 6.x / 7.x）NVIDIA 官方文档的 configure 开关（新版对照）
./configure \
--enable-cuda-nvcc \
--enable-cuvid \
--enable-nvdec \
--enable-nvenc \
--enable-nonfree \
--enable-libnpp \
--extra-cflags=-I/usr/local/cuda/include \
--extra-ldflags=-L/usr/local/cuda/lib64| configure 选项 | 作用 | 说人话 |
|---|---|---|
--enable-cuda-sdk | 启用 CUDA SDK | 旧名，新版改名 --enable-cuda-nvcc |
--enable-cuvid | 编译 GPU 解码器 | 让 FFmpeg 认识 h264_cuvid 等解码器 |
--enable-nvenc | 编译 GPU 编码器 | 让 FFmpeg 认识 h264_nvenc 等编码器 |
--enable-nonfree | 接受非自由许可 | NVENC 许可不自由，必须显式声明 |
--enable-libnpp | 启用 NPP 图像库 | scale_npp 等 GPU 滤镜的靠山 |
--extra-cflags / --extra-ldflags | 指向 CUDA 头文件与库 | 告诉编译器去 /usr/local/cuda 找人 |
注意：--enable-nonfree 不是可选项，是硬门槛。不加它，configure 会在"License: nonfree"这一关拒绝编译 nvenc——因为 NVENC 的许可证与 FFmpeg 的 LGPL/GPL 不兼容，属于非自由组件。自己编译自己用没问题；但带 NVENC 的二进制不能按 GPL 自由分发，商用分发前务必先读许可证。素材里这一行是加了 --enable-nonfree 的，别学漏。
这是本章的核心案例，也是素材里最有戏剧性的一段。作者编译 nv-codec-headers 时用的是最新版本 9.1，结果编译出错。素材原文只记了"编译出错"四个字，没贴报错文本——但原理可以推理：头文件 9.1 声明的是新版 SDK 的接口，而驱动 410.48 的固件只提供旧版接口，头文件要求的能力超出了驱动实际提供的能力，自然对不上。素材里的完整环境是（素材实录）：
# 素材实录：出问题时的完整版本清单
ffmpeg 版本 ffmpeg version n4.1.1-3-g53f3f52
cuda 版本 CUDA Version 10.0.130（这个版本自带驱动，可以不用安装驱动）
drive 驱动版本 Driver Version: 410.48
nv-codec-headers 版本 sdk/8.1报错之后有两条路，素材原文逐条评估过：路 A——升级驱动到 430 以上，让驱动固件跟上头文件的 API。麻烦在哪？要换驱动、可能要重启、可能影响服务器上正在跑的服务，动静太大。素材原话："这个比较的麻烦"。路 B——降低 nv-codec-headers 的版本到 8.1，让头文件去迁就驱动。成本就一个 git checkout。作者选了路 B，一次成功。这就是诸葛亮式的决策：把变量列全，比较每条路的代价，选改动最小的那条：
# 报错后的决策过程（诸葛亮式：列变量 → 比代价 → 选路）
变量清单：驱动 410.48（CUDA 10.0.130 自带）· 头文件 9.1（最新）· FFmpeg n4.1.1
路 A：升级驱动到 430+ —— 换驱动、可能重启、影响线上服务（麻烦）
路 B：降头文件到 8.1 —— 一个 git checkout 的事（改动最小）<- 作者的选择，成功| 驱动版本 | nv-codec-headers | FFmpeg | 结果 |
|---|---|---|---|
| 410.48 | sdk/9.1（最新） | n4.1.1 | 编译出错（头文件 API 超出驱动能力） |
| 410.48 | sdk/8.1 | n4.1.1 | 编译成功（素材实证） |
| 430+ | sdk/9.1 | n4.1.1 | 可行（另一条路） |
注意：记住版本匹配三件套——驱动 ↔ 头文件 ↔ FFmpeg，三者必须匹配。素材是 2019-2020 年的 CUDA 10.0 / 驱动 410.48 环境；到了 2026 年，NVIDIA 驱动早已是 5xx/6xx 系列，nv-codec-headers 的发布标签也换成了 n11.x / n12.x 这类名字——具体数字全变了，但"驱动决定能力上限、头文件声明接口、FFmpeg 按声明编译，三者对不上就出错"的原则一条没变。遇到报错，先查三者的版本对应关系，别闷头重试。
版本冲突的取舍口诀：改动最小优先。升级驱动 / 升级系统属于高风险、大影响面的动作，降级一个库通常是低风险、局部的小动作。素材这次"降 8.1 成功"是教科书式的取舍；反过来，如果你的驱动很新而头文件很旧，那就是升级头文件——方向永远是把两边拉到同一个 SDK 代际上。
编译装完不等于成功，诸葛亮还要"验功"。第一步看硬件加速方法：ffmpeg -hwaccels 列出编译时真的启用（编进去）的硬件加速方法；第二步看解码器：ffmpeg -codecs | grep cuvid 直接确认 cuvid 系解码器是否编译进来（应能看到 h264_cuvid 等以 _cuvid 结尾的 GPU 解码器）。素材实录：
# 素材实录：查看支持的硬件加速选项
ffmpeg -hwaccels
# 素材实录：查看 cuvid 提供的 GPU 编解码器（应看到 h264_cuvid 等）
ffmpeg -codecs | grep cuvid第三步，真正转一段，转码期间用 nvidia-smi 看 GPU 利用率——如果 GPU 那一栏在跳动，说明 FFmpeg 确实在用显卡干活。素材实录的 GPU 转码命令（注意与软转码的差别，第 8 章会逐参数拆解）：
# 素材实录：GPU 转码——h264 源转成指定尺寸与码率的 h264 输出
ffmpeg -hwaccel cuvid -c:v h264_cuvid -i video/video-H264-AAC.mkv -c:v h264_nvenc -b:v 2048k -vf scale_npp=1280:-1 -y /root/transcode.mp4
# -hwaccel cuvid：启用 cuvid 硬件加速；-c:v h264_cuvid：GPU 解码
# -c:v h264_nvenc：GPU 编码；-vf scale_npp=1280:-1：GPU 缩放（不是 -vf scale）为什么必须显式点名 h264_cuvid？素材原文点透了：ffmpeg 只会自动选择 CPU 解码器，要让 FFmpeg 使用 GPU 解码器，必须先用 ffprobe 识别出输入视频的编码格式（第 3 章的本职工作），然后在命令行里显式指定对应的 GPU 解码器——这就是 -hwaccel cuvid -c:v h264_cuvid 组合存在的意义。
注意：验证是"体检"，不是"仪式"。ffmpeg -hwaccels 只显示编译时真的编进去的方法——如果输出里没有 cuvid，说明 configure 没开对应选项、或 nv-codec-headers 没装好、或版本不匹配（回到 7.3 / 7.4），改完必须重新 configure 并重新 make，光改配置不重编是无效的。别在缺了选项的二进制上浪费时间排查。
验证顺序就是排错顺序：先 -hwaccels 看有没有这个加速方法，再 -codecs | grep cuvid 看解码器，再 -encoders | grep nvenc 看编码器，最后转码时 nvidia-smi 看是不是真的在 GPU 上跑。四步全过，才算"决胜千里"。
本教程的实测环境是 macOS（Apple Silicon，arm64）上的 Homebrew ffmpeg-full 8.1.1——没有 NVIDIA 显卡，素材里的 NVIDIA 命令无法原样复现。那就如实记录，顺便演示"验证三连"在别的平台上长什么样。先跑 ffmpeg -hwaccels（本机真实输出）：
# 本机实测（macOS arm64，ffmpeg 8.1.1）：支持的硬件加速方法
ffmpeg -hwaccels
Hardware acceleration methods:
videotoolbox
vulkan没有 cuvid——因为既没有 NVIDIA 显卡，也没有编译 NVIDIA 支持。苹果平台的硬编解码走 VideoToolbox（macOS 系统的硬编解码框架，说人话：苹果官方提供给应用调用 GPU 编解码的通道），对应的 configure 开关是 --enable-videotoolbox。再跑第二、三步验证：NVIDIA 编解码器在本机一个都没有（grep 无输出是真实结果），而苹果平台的 GPU 编码器一查一个准（本机真实输出）：
# 本机实测：NVIDIA 编解码器均为空（无 NVIDIA 硬件，如实记录）
ffmpeg -encoders 2>/dev/null | grep -i nvenc # 无输出
ffmpeg -decoders 2>/dev/null | grep -i cuvid # 无输出
# 本机实测：macOS 的 GPU 编码器走 VideoToolbox 框架
ffmpeg -encoders 2>/dev/null | grep -i videotoolbox
V....D h264_videotoolbox VideoToolbox H.264 Encoder (codec h264)
V....D hevc_videotoolbox VideoToolbox H.265 Encoder (codec hevc)
V....D prores_videotoolbox VideoToolbox ProRes Encoder (codec prores)# 本机实测：VideoToolbox 的解码不是独立解码器，而是挂在 hwaccel 上的方法
ffmpeg -decoders 2>/dev/null | grep -i videotoolbox # 无输出（与 NVIDIA 的 h264_cuvid 族不同）注意上面这个空输出：VideoToolbox 的解码加速是挂在 -hwaccel videotoolbox 上的通用方法，配合普通解码器使用，而不是像 NVIDIA 那样生成一组独立的 *_cuvid 解码器——所以 ffmpeg -decoders | grep videotoolbox 为空是正常现象，别当成故障。
| 平台 | 硬编解码方案 | configure 开关 | 验证方法 |
|---|---|---|---|
| NVIDIA GPU（Linux） | NVENC / NVDEC（cuvid） | --enable-cuvid --enable-nvenc --enable-nonfree | -hwaccels / -codecs | grep cuvid |
| Intel 核显 | QSV（Quick Sync Video） | --enable-qsv | ffmpeg -hwaccels |
| AMD GPU | AMF | --enable-amf | ffmpeg -hwaccels |
| Apple Silicon / macOS | VideoToolbox | --enable-videotoolbox | ffmpeg -hwaccels |
| 通用 Linux | VDPAU / VAAPI | --enable-vdpau / --enable-vaapi | ffmpeg -hwaccels |
换平台先问一句"我的硬编解码走哪条路"，ffmpeg -hwaccels 就是答案。configure 开关随平台而变，但本章的招式完全通用：侦察（看硬件）→ 配置（加开关）→ 编译（带头文件）→ 验证三连。在 NVIDIA 机器上把这套流程走通，换到 Intel / AMD / Apple 机器只是换几个开关名字。
最后埋个钩子。素材的 GPU 转码章节还有一段"在容器中使用 NVIDIA"的记录：服务打包成 Docker 镜像后，怎么都调不到 NVIDIA 硬件，最后查遍资料，发现要在 Dockerfile 里加一行环境变量 ENV NVIDIA_DRIVER_CAPABILITIES video,compute,utility 才能让容器里调用成功——这是典型的"编译对了、运行环境没配"的坑，连同 -hwaccel cuvid 转码命令的逐参数拆解，留给第 8 章 GPU 转码实战与容器部署（狄仁杰导师，系统分析专场）。这一章先把"配置与版本匹配"的棋局下好，下一章就可以放心地让 GPU 跑起来了。
把左边的术语与右边的解释配对：① NVENC；② NVDEC；③ --enable-nonfree；④ nv-codec-headers。候选解释：A. 显卡里的专用解码单元（旧名 CUVID）；B. FFmpeg 官方维护的 NVIDIA SDK 头文件；C. 显卡里的专用编码单元；D. 编译 NVENC 必需的"接受非自由许可"开关。
回顾 7.1 节：NVENC 编码、NVDEC 解码；7.3 节的表格里 --enable-nonfree 和 nv-codec-headers 各自在解决什么问题？
① → C（NVENC，专用编码单元）；② → A（NVDEC，专用解码单元，旧名 CUVID）；③ → D（接受非自由许可，NVENC 许可证不自由，不加它 configure 拒绝编译）；④ → B（FFmpeg 官方维护的 NVIDIA SDK 头文件，编译时把 nvenc / cuvid 编解码器焊进 FFmpeg）。口诀：编 NVENC、解 NVDEC、许可 nonfree、接口靠头文件。
素材场景：驱动 410.48 + nv-codec-headers 最新版 9.1，编译 FFmpeg 报错。两个解法分别是什么？作者选了哪个，为什么？9.1 在 410.48 上为什么不行？
回顾 7.4 节的两条路：升级谁、降级谁，各自的代价；再想想"驱动固件提供能力、头文件声明接口"这层关系。
解法 A：升级驱动到 430+（让固件跟上头文件的 API，但麻烦、影响面大）；解法 B：降 nv-codec-headers 到 8.1（一个 git checkout，改动最小）。作者选了 B 并成功。9.1 在 410.48 上不行，是因为头文件 9.1 声明的是新版 SDK 接口，而驱动 410.48 的固件只提供旧版能力——头文件要求的超出了驱动实际提供的，编译必然对不上。取舍口诀：改动最小优先，先把两边拉到同一个 SDK 代际。
在 NVIDIA 机器上编译完 FFmpeg，发现 ffmpeg -hwaccels 没有 cuvid，ffmpeg -codecs | grep cuvid 为空。按正确顺序排出排查步骤：a. 重新 ./configure + make 后再验证；b. 检查 configure 是否加了 --enable-cuvid / --enable-nvenc / --enable-nonfree；c. 检查 nv-codec-headers 是否已安装、版本是否与驱动匹配；d. 检查 --extra-cflags / --extra-ldflags 的 CUDA 路径是否正确。
7.5 节的 warning 给了思路：先查配置（开关），再查依赖（头文件），改完必须重新编译。
正确顺序：b → c → d → a。先确认开关开没开（7.3），再确认头文件装没装、版本对不对（7.4），再确认 CUDA 路径指向对不对（--extra-cflags / --extra-ldflags），最后重新 configure 并 make——注意顺序里的教训：任何一步改动后都必须重新编译，且验证动作（ffmpeg -hwaccels）永远在最后一步做。
在自己机器上完成本章的"侦察 → 配置 → 验证"闭环：① 跑 ffmpeg -hwaccels 看自己的平台支持哪些硬件加速方法；② 判断你的平台属于哪一类（NVIDIA → cuvid/nvenc；Intel → qsv；AMD → amf；Apple → videotoolbox），写出对应的 configure 开关；③ 如果你有 NVIDIA GPU 的 Linux 机器，完整走一遍：lspci 看显卡 → nvidia-smi 看驱动 → 用 7.5 节的素材命令转码，转码中观察 nvidia-smi 的 GPU 利用率。把每步输出记录下来。
命令都在 7.2 / 7.5 / 7.6 节出现过；NVIDIA 转码命令是 ffmpeg -hwaccel cuvid -c:v h264_cuvid -i 输入 -c:v h264_nvenc -b:v 2048k -vf scale_npp=1280:-1 输出；转码时另开一个终端看 nvidia-smi。
① 苹果本机输出是 videotoolbox + vulkan（见 7.6 节实测）；② Apple 平台对应 --enable-videotoolbox，NVIDIA 平台对应 --enable-cuvid --enable-nvenc --enable-nonfree；③ NVIDIA 机器上，转码期间 nvidia-smi 的 GPU 利用率应明显跳动、而 CPU 占用远低于软转码——这就是"GPU 真的在干活"的铁证。三关全过，你就亲手走完了本章"先调查、再配置、后验证"的完整闭环。