Docker 构建可复现 FFmpeg 转码环境与硬件编码实践

FFmpeg 这个东西，用得多的人都有个共同体会：真正让人头疼的从来不是命令行参数怎么写，而是"上个月在 A 机器上编好的那套，换到 B 机器上怎么又找不到 libx264 了"。我把这套环境搬进 Docker 之后，类似的问答基本消失了。这篇文章讲的就是我这两年反复折腾出来的一整套做法：怎么用 Docker 搭一个干净、可复现、带硬件编码能力的 FFmpeg 运行环境，从镜像怎么选、Dockerfile 怎么写、挂载和权限怎么配，到批量任务跑起来之后会撞上的那些具体问题。内容偏实操，适合已经会敲几行 ffmpeg 命令、但在多机部署或生产批量转码上吃过亏的同学；如果你完全没碰过容器，只要跟着命令走也能跑通，我会在关键处解释为什么这么做。

1. 把 FFmpeg 放进容器到底解决了什么

1.1 编解码器的依赖关系是最先失控的地方

原生装 FFmpeg 最省事的路径是包管理器一把梭，apt install ffmpeg或者yum install ffmpeg，两秒钟搞定。问题在于发行版仓库里的那个包，是发行版维护者按自己的策略编译的。它可能带了 libx264，可能没带 libx265，可能带的是某个较老的 libvpx，也可能把 libfdk_aac 这类授权条款比较特殊的库直接排除在外。

我在某个项目上就吃过这个亏：本地环境自己编译的 FFmpeg 支持-c:a libfdk_aac，脚本里写死了这个编码器，部署到服务器上换成包管理器装的版本，命令直接报Unknown encoder 'libfdk_aac'，整个转码流水线停在第一个文件上。这种错误的烦人之处在于它不在开发阶段暴露，而是在上线之后、处理真实素材的时候才炸。

容器在这里的价值不是"更先进"，而是"更确定"。镜像里的 FFmpeg 是你自己编译的那一份，ffmpeg -encoders打印出来的列表是固定的，不会因为宿主机换了发行版、升了个小版本就变样。

1.2 从"我这能跑"到"你那也能跑"之间的鸿沟

更隐蔽的一类问题是动态库版本。FFmpeg 编译出来依赖一堆 so 文件，原生安装时这些库散落在/usr/lib/x86_64-linux-gnu、/usr/local/lib这些地方，靠ldconfig缓存找。两个人机器上装的库版本差一点点，链接时就可能出问题，报错信息还特别不友好——通常是undefined symbol: xxx之类，看完一脸茫然。

容器把这层依赖整个封在镜像里。镜像跑起来，ldd $(which ffmpeg)的输出是构建时确定的，跟宿主机装了什么完全无关。宿主机只需要提供内核和一点点运行时支撑，其余全部隔离。

这一点在混合环境里尤其明显。团队里有人用较新的发行版、有人还在用旧版本、有人是 ARM 架构的机器，只要镜像构建的架构对应，行为就是一致的。我做跨平台批处理的时候，同一个镜像在 x86 服务器和 ARM 小主机上跑出来的输出文件，用ffprobe对比参数，码率、帧率、编码器版本都能对上。

1.3 容器带来的不是性能，别指望它更快

得先把一个预期纠正过来：Docker 不是虚拟机，它不模拟硬件，也不做指令翻译，本质上是内核的命名空间和 cgroup 隔离。所以 FFmpeg 在容器里跑，跟直接在宿主机跑，CPU 密集型的转码性能差异通常在个位数百分比以内，这部分差异主要来自文件系统层（overlay 或者 bind mount）的 I/O 开销，而不是计算本身。

我做过一组粗糙的对比，同一个 1080p 素材、同样的-c:v libx264 -preset medium -crf 23参数：

结论很清楚：挂载方式对性能的影响，比"是否用容器"大得多。如果跑的是长任务、大文件，尽量用 bind mount 直挂宿主机目录，别让数据在卷和容器层之间来回倒腾。

注意：如果你的容器把大量中间文件写在容器自身的可写层里，任务结束时容器一删，这些数据也跟着没了。中间文件要么挂出来，要么明确接受它的临时性。

2. 镜像来源的三条路，各自的适用边界

2.1 官方镜像够用，但你得先确认它编了什么

最省心的起步方式是直接拉官方的 FFmpeg 镜像。它的好处是体积小、更新勤、构建脚本公开。但很多人在这一步会踩坑：官方镜像为了控制体积和规避授权问题，默认编译进去的编码器是有限的，--enable-gpl这个开关通常是关的，这意味着 libx264、libx265 这些 GPL 系的库可能不在里面。

判断方法很简单，拉下来跑一条命令：

docker run --rm ffmpeg -hide_banner -encoders | grep -E "libx264|libx265|libvpx"

如果输出是空的，说明这个镜像满足不了你的需求。这一步我建议每次都做，别靠记忆，因为不同 tag 的编译参数是会变的。

如果你的场景只是做简单的封装转换（比如把 mkv 换成 mp4，编码器全用 copy）、抽帧、截取片段、生成缩略图，官方镜像是完全够的。这类操作不涉及重新编码，用-c copy走流拷贝，性能开销极小，没必要为了编解码器去自建镜像。

2.2 社区镜像的便利与它的不确定性

社区里有一些维护得不错的 FFmpeg 镜像，特点是"全"——把常见的编码库都编进去了，还内置了一些硬件加速支持。拿来即用，省去编译的几十分钟。

问题在于两个。第一，你不知道它是哪天用哪个版本的源码编的，镜像 tag 里不写这些信息的话，出问题很难回溯。第二，这类镜像体积往往不小，几百兆到一两个 G 都有，因为它们把编译工具链也留在里面了。

我的做法是：评估、临时验证可以用社区镜像，但真正进流水线的镜像必须来自自己可控的构建过程。原因不在信任问题，而在可追溯性——生产环境里某个文件转出来颜色偏了、时间戳错了，你总得能查到当时用的是哪个版本的库。

2.3 什么时候必须自建

下面这几种情况，自建基本是唯一选择：

• 需要 GPL 系的编码库（libx264、libx265），又不能用官方镜像的构建参数
• 需要某个较新的特性，比如某个滤镜是最近才合进主干的
• 需要硬件编码，且要求特定版本的头文件配合驱动
• 需要精简体积，把镜像压到一两百兆以内做边缘部署
• 需要在构建时打补丁，改掉某个行为不符合预期的默认值

自建的代价是构建时间长、需要维护一份 Dockerfile。但一旦这份 Dockerfile 稳定下来，后面几个月都不用碰它，反而比每次装环境省事。

3. 一份能长期用的 Dockerfile 是怎么长出来的

3.1 基础镜像与构建依赖的取舍

基础镜像我一般选"最小稳定发行版"，比如debian:bookworm-slim这类。理由有几个：包管理器成熟，依赖好找；glibc 版本比较新，编译较新的源码不会卡版本；社区资料多，遇到问题好查。

不选 Alpine 的原因得说清楚。Alpine 用 musl libc，体积确实小，但 FFmpeg 生态里不少第三方库对 musl 的支持并不完善，编译时容易出各种奇怪的链接错误；而且一旦要接硬件加速或者某些闭源运行时，musl 的兼容性更差。为了省那几十兆去赌编译顺利，我觉得不划算，除非你明确知道自己的依赖链在 musl 下没问题。

构建依赖清单，我踩过几次坑之后固定成这样：

FROM debian:bookworm-slim AS build ARG FFMPEG_VERSION=6.1.1 RUN apt-get update && apt-get install -y --no-install-recommends \ build-essential \ pkg-config \ nasm \ yasm \ git \ ca-certificates \ wget \ xz-utils \ libssl-dev \ zlib1g-dev \ libass-dev \ libfreetype6-dev \ libfribidi-dev \ libharfbuzz-dev \ libfontconfig1-dev \ libmp3lame-dev \ libopus-dev \ libvorbis-dev \ libvpx-dev \ libx264-dev \ libx265-dev \ libnuma-dev \ && rm -rf /var/lib/apt/lists/*

几个细节值得单独说：

nasm和yasm两个都要装。x264 和 x265 的汇编优化依赖它们，缺了会编译得极慢甚至直接失败。新版 x264 主要用 nasm，但有些库还认 yasm。

libnuma-dev是给 x265 用的，缺了会在 configure 阶段报找不到 numa，然后你可能会选择关掉它，结果 x265 在多路并发下的性能明显打折。

libfontconfig1-dev加上libfreetype6-dev是drawtext滤镜的前提。这个滤镜用得非常频繁——加水印、加时间戳、加文字说明都靠它。很多人编译完发现No such filter: 'drawtext'，就是这两个库没装。

至于libx264-dev/libx265-dev，用发行版提供的开发包还是自己从源码编，是个取舍。发行版包省事、版本稳定；自己编能拿到更新的版本和更精细的编译参数。我一般先用发行版包，如果遇到某个编码特性缺失再改成源码编译。源码编译要多写几十行，还得处理pkg-config路径，不是必须就别折腾。

3.2 configure 参数逐项拆开看

这是整个构建里最需要理解的部分。我用的配置大概是这样：

./configure \ --prefix=/usr/local \ --disable-doc \ --disable-debug \ --disable-ffplay \ --enable-gpl \ --enable-libx264 \ --enable-libx265 \ --enable-libvpx \ --enable-libmp3lame \ --enable-libopus \ --enable-libvorbis \ --enable-libass \ --enable-libfreetype \ --enable-libfribidi \ --enable-libfontconfig \ --enable-libharfbuzz \ --enable-shared \ --disable-static \ --enable-pic

逐条解释一下为什么：

--disable-doc和--disable-debug纯粹是瘦身。文档和调试符号在运行环境里没用，关掉能省不少体积和编译时间。--disable-ffplay是因为 ffplay 依赖 SDL，容器里根本没图形界面，编了也是废的，还得额外装一堆库。

--enable-gpl是打开 GPL 系库支持的开关。只有加上它，--enable-libx264和--enable-libx265才会真正生效，否则 configure 会静默跳过。这个坑我提一句，因为它不报错，你编完了才发现编码器列表里没有。

--enable-shared --disable-static --enable-pic三个一起用，是为了生成动态库而不是静态链接进二进制。动态链接的好处是最终镜像可以只保留 so 文件加二进制，体积小；坏处是运行时得保证库路径正确，需要配LD_LIBRARY_PATH或者打个 ldconfig 配置。我倾向动态，因为多阶段构建时裁剪更干净。

3.3 多阶段构建把镜像从 1.2G 压到 200M 出头

编译过程需要的那一大堆 dev 包，运行时一个都用不上。如果单阶段构建，这些包全留在镜像里，体积轻松破 G。多阶段构建的做法是把编译产物拷到一个干净的基础镜像里：

RUN ./configure ... \ && make -j"$(nproc)" \ && make install DESTDIR=/out FROM debian:bookworm-slim RUN apt-get update && apt-get install -y --no-install-recommends \ libx264-164 \ libx265-199 \ libvpx7 \ libmp3lame0 \ libopus0 \ libvorbis0a \ libass9 \ libfreetype6 \ libfribidi0 \ libfontconfig1 \ libharfbuzz0b \ && rm -rf /var/lib/apt/lists/* COPY --from=build /out/usr/local/ /usr/local/ RUN ldconfig ENTRYPOINT ["ffmpeg"] CMD ["-hide_banner"]

这里有个坑必须提醒：运行时镜像里装的 so 包，版本号必须和构建阶段用的一致。上面写的libx264-164这种带数字后缀的包名，在不同发行版版本上数字不一样。稳妥的办法是在构建阶段先dpkg -l | grep libx264看一眼实际版本，照着填；或者干脆把编译出来的 so 也一起拷过去，只拷自己编的那份，不依赖系统包。

我试过第二种，代价是得把 x264、x265 这些库的 so 也编出来并拷进最终镜像，镜像会大一点（大概多三四十兆），但彻底解耦，不会因为基础镜像升级导致缺库。生产环境我选这个方案，图个稳。

ENTRYPOINT ["ffmpeg"]这个设计很关键。设成 entrypoint 之后，运行命令可以写成docker run ... 镜像 -i input.mp4 ...，参数直接透传，读起来跟本地敲 ffmpeg 几乎一样。如果 entrypoint 是 shell 或者留空，就得写docker run ... 镜像 ffmpeg -i ...，啰嗦还容易漏。

同时因为 entrypoint 是 ffmpeg 而不是 shell，容器里的 PID 1 就是 ffmpeg 进程，收到docker stop的 SIGTERM 时会正常处理退出，不会出现进程被强行杀掉、输出文件损坏的情况。这一条在处理大文件时特别重要。

3.4 版本锁定与构建缓存

Dockerfile 里用ARG FFMPEG_VERSION=6.1.1把版本号提出来，构建时可以用--build-arg覆盖。这样同一份 Dockerfile 既能出稳定版镜像，也能临时试新版。

构建缓存方面，把"装依赖"和"下载源码"分成两层，改源码版本时不会让依赖层缓存失效：

RUN apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/* ARG FFMPEG_VERSION RUN wget -q "https://example.invalid/ffmpeg-${FFMPEG_VERSION}.tar.xz" -O /tmp/ffmpeg.tar.xz

源码地址换成对应版本的实际下载地址即可。把ARG放在RUN之前，但只要RUN命令文本不变，缓存就还在；改--build-arg的值会让这一层重建，前面的依赖层不受影响。这个顺序我调过好几次才找到比较舒服的组合。

完整构建一次大概十几分钟（取决于机器核数），make -j$(nproc)的nproc别改小，编译 FFmpeg 是典型的多核友好任务，八核和双核能差出三四倍时间。

4. 挂载、权限与信号：运行阶段最容易翻车的地方

4.1 目录设计比命令本身更重要

我习惯在宿主机上把工作目录切成三块：输入、输出、临时。容器里对应挂三个路径，输入目录挂成只读：

docker run --rm \ -v /data/media/in:/work/in:ro \ -v /data/media/out:/work/out \ -v /data/media/tmp:/work/tmp \ ffmpeg:6.1 \ -i /work/in/input.mkv \ -c:v libx264 -preset medium -crf 23 \ -c:a aac -b:a 192k \ -y /work/out/output.mp4

输入挂:ro是我强制自己的规矩。有一次脚本写错了，输出路径拼成了输入路径，直接把源文件覆盖了。虽然那次是测试素材，但那种心跳加速的感觉不想再来第二次。挂只读之后，同样的错误会立刻报权限拒绝，损失为零。

临时目录单独挂出来也有讲究。FFmpeg 在两遍编码（比如两遍降噪、两遍分析）或者某些滤镜链里会写临时文件，默认写到/tmp，而/tmp在容器里属于可写层，大文件写进去可能把容器撑爆。显式挂一个够大的临时目录，问题就绕过去了。可以用-t参数指定临时文件位置，也可以在容器里设环境变量TMPDIR=/work/tmp，后者更省事：

docker run --rm -e TMPDIR=/work/tmp -v /data/media/tmp:/work/tmp ...

4.2 UID/GID 不一致导致输出文件属主是 root

这是新手必踩的坑：容器里默认以 root 跑，写出来的文件在宿主机上属主就是 root（或者某个高 UID），后面用普通用户去移动、删除、再次处理就各种权限拒绝。

解决办法是运行时把当前用户的 UID 和 GID 传进去：

docker run --rm \ -u "$(id -u):$(id -g)" \ -v "$PWD/out:/work/out" \ ffmpeg:6.1 \ -i /work/in/input.mkv -c copy /work/out/output.mp4

但这里有连锁反应：镜像里如果用的是ENTRYPOINT ["ffmpeg"]，非 root 用户执行不受影响；可一旦你需要在容器里执行别的命令、写某些目录，非 root 就可能被拒。所以更稳的做法是构建镜像时就建一个跟宿主机常用 UID 对应的用户，或者干脆让镜像里的目录权限是 777（仅限内部环境，生产环境慎用）。

我在流水线里用的是-u方案，配合--read-only和--tmpfs /tmp做加固。有一说一，这套组合在简单转码任务上很舒服，一旦涉及写临时大文件就要多配一个可写的挂载点，配置会变长，看场景取舍。

注意：-u参数传入的 UID 必须在镜像的/etc/passwd里有记录（或者至少不影响执行），否则某些工具会打印I have no name!这样的警告。对 ffmpeg 本身无影响，但日志会变脏。

4.3 信号传递：为什么大文件转码最怕突然被停

前面提过 entrypoint 直接用 ffmpeg 能让它成为 PID 1。但如果你的命令外面包了一层 shell 脚本（比如bash -c "ffmpeg ... && echo done"），shell 成了 PID 1，它默认不会把信号转发给子进程。结果是docker stop发出 SIGTERM 之后，shell 收下了，ffmpeg 还在闷头跑，等宽限期（默认 10 秒）一过，内核直接把整个容器干掉。

对大文件转码来说，这意味着 mp4 的 moov 原子没写完整，输出文件直接废掉，白白浪费几十分钟。

两个解决方向。简单的是给docker run加--init，让一个极小的 init 进程做 PID 1，负责信号转发和回收僵尸进程。另一个是写成脚本时显式处理：

#!/bin/sh set -e trap 'kill -TERM "$child" 2>/dev/null' TERM INT ffmpeg "$@" & child=$! wait "$child"

我现在的做法是：命令简单的场合直接透传，不加外壳；确实需要脚本处理批量逻辑的，一律加--init或者--stop-timeout 120把宽限期拉长，让 ffmpeg 有时间把文件收尾。

4.4 资源边界别交给默认值

容器的 cgroup 限制会影响 FFmpeg 的并发行为。nproc在容器里读的是 CPU 配额而不是宿主机的物理核数，所以-threads 0（自动）在配额为 2 的容器里会只开 2 个线程，这通常是好事。

但反过来，如果没设--cpus，容器能吃到宿主机全部核心，同时跑好几个转码任务时，几个进程互相抢，整体吞吐反而下降。我的做法是明确设定：

docker run --rm \ --cpus="4" \ --memory="4g" \ --memory-swap="4g" \ ffmpeg:6.1 ...

--memory-swap设成和 memory 一样，是为了禁用 swap。转码是内存访问密集型任务，一旦开始 swap，性能会断崖式下跌，而且表现出来就是"莫名其妙的慢"，很难联想到内存。禁掉之后如果内存真不够，进程会被 OOM killer 干掉，日志里至少能看到退出码 137，比慢慢变卡好排查。

5. 硬件编码进容器的前提条件

5.1 软件编码和硬件编码不是替代关系

先说结论：硬件编码快，但同码率下的画质通常不如软件编码，这是编码器实现深度决定的，不是参数能完全弥补的。所以我的选择逻辑是：

• 归档、母版、需要追求画质的场合：软件编码（libx264 / libx265），慢就慢
• 实时转码、预览、批量生成低码率副本、监控录像归档：硬件编码，速度优先
• 只需要改容器格式、不动编码：-c copy，两者都不用

这个判断做错了会很痛苦。我见过用硬件编码生成归档母版的，文件是小了，但暗部出现了明显的块状伪影，发现时已经处理了几百个文件。

5.2 设备直通需要宿主机先备好

容器里用硬件编码，本质是让容器能访问宿主机的设备节点。前提条件按顺序是：

1. 宿主机装好显卡驱动，ffmpeg在宿主机上（如果有的话）能正常用硬件编码器
2. 装好容器设备直通组件，这部分现在多数发行版的包管理器都有现成包，装完重启容器服务生效
3. 用--gpus all或者--device /dev/dri之类的参数把设备交给容器

驱动没装好就直接跑容器，报错通常是Cannot load libcuda.so.1或者Failed to initialise VAAPI connection，看着像镜像问题，实际是宿主机的事。

对集成显卡或者某些平台，走的是/dev/dri设备节点：

docker run --rm \ --device /dev/dri:/dev/dri \ -v /data/media/in:/work/in:ro \ -v /data/media/out:/work/out \ ffmpeg:6.1 \ -hwaccel vaapi -hwaccel_device /dev/dri/renderD128 \ -i /work/in/input.mkv \ -c:v h264_vaapi -b:v 4M \ /work/out/output.mp4

-hwaccel是解码加速，-c:v h264_vaapi是编码加速，两个可以只用一个。很多场景下解码用软件、编码用硬件，画质会好一些，因为软件解码的帧处理更精确。这个组合值得试。

5.3 实测差异与失败时的现象

同素材、同目标码率的粗略对比：

从这组数据能看出来，硬件编码的优势是数量级的，一个小时的素材几分钟处理完。如果你的场景是"先出一版给客户看，确认后再用软件编码出终版"，这个速度差足以改变工作流。

失败时的典型现象也要认识一下。硬件编码器初始化失败时，FFmpeg 会打印一行Cannot load libxxx.so或者Device creation failed，然后整个命令退出，不会静默降级到软件编码。这意味着你的批处理脚本必须在第一个文件上就发现问题，而不是跑完一百个之后才发现全是硬件编码失败。我的做法是在批处理开头先拿一个三秒的测试片段跑一遍，通过了再开始批量。

6. 批量任务的落地形态

6.1 一次性容器还是常驻容器

两种形态我都在用，取决于任务特征。

一次处理一批文件就结束的，用一次性容器最干净：docker run --rm跑完即焚，不会留下状态。启动开销在百毫秒级，相比动辄几分钟的转码可以忽略。

需要处理的任务量很大、并且希望复用容器启动开销的，我会起一个常驻容器，把 ffmpeg 换成 shell 或者一个轻量守护进程，然后docker exec进去执行命令。这样省掉反复创建容器的开销，也方便进容器里排查。

不过常驻容器有个副作用：容器内的/tmp会随着任务积累垃圾。我一般会在脚本里加一句清理，或者在 compose 里配tmpfs让/tmp走内存、容器重启就清空。

6.2 进度解析：别只看日志文本

批量跑起来之后，你需要知道进度。FFmpeg 默认往 stderr 输出进度，是可读文本，但解析起来麻烦。更稳妥的做法是用-progress输出结构化数据：

ffmpeg -i input.mkv -c:v libx264 -progress pipe:1 -nostats output.mp4

-progress pipe:1会把键值对格式的进度信息打到标准输出，形如frame=123、out_time_ms=...、progress=continue。解析这些比正则有规律得多，不需要去匹配time=00:01:23.45那种格式。

-nostats用来关掉默认的 stderr 进度行，让日志干净。两个参数我基本成对使用。

失败重试的逻辑也要小心。转码失败有时候是硬件编码器偶发初始化失败，重试一次就能过；有时候是源文件本身损坏，重试一百次也没用。我的做法是重试两次，两次都失败就跳过并记录，不阻塞整批任务。整批跑完再回头看失败清单，手动处理。

6.3 并发数怎么定

并发不是越大越好。一个编码进程的线程数是有上限的——libx264 默认会用掉所有可用核心，两个这样的进程同时跑，线程数直接超卖，上下文切换开销会把性能吃回去。经验值：并发数 = 可用核心数 / 单个任务实际用到的核心数，取整后再减一，留点余量给系统。

更省事的办法是用-threads显式限制单任务线程数。比如 8 核机器上跑 4 个并发，每个限制 2 线程：

for f in /data/media/in/*.mkv; do name=$(basename "$f" .mkv) docker run --rm \ -v /data/media/in:/work/in:ro \ -v /data/media/out:/work/out \ ffmpeg:6.1 \ -i "/work/in/${name}.mkv" \ -c:v libx264 -preset medium -crf 23 -threads 2 \ -c:a copy \ -y "/work/out/${name}.mp4" & while [ "$(jobs -r | wc -l)" -ge 4 ]; do sleep 2; done done wait

这只是个思路示意，实际用的时候我会换成更明确的队列控制，因为 shell 的jobs在复杂场景下不太可控。关键是那个-threads 2，它是让并发真正有效的开关。

另外，大量小文件并发时，容器创建的频率会很高，此时把--rm去掉、改用固定容器名并通过docker exec执行，会比反复创建更快。

7. 排查链路：几个我实打实踩过的坑

7.1 报 Unknown encoder，但编译参数明明写了

这是我遇到最多、也是排查起来最绕的一类问题。明明 Dockerfile 里写了--enable-libx264，构建过程也没报错，跑起来就是Unknown encoder 'libx264'。

完整排查路径是这样的：

第一步，进容器看 configure 信息：

docker run --rm --entrypoint ffmpeg ffmpeg:6.1 -hide_banner -buildconf

如果输出里没有--enable-libx264，说明 configure 阶段就没生效，问题在构建。原因通常是缺了--enable-gpl，或者缺了对应的 dev 包，configure 在找不到库时会静默跳过这个选项。这是 configure 的行为特点，它不会因为某个--enable-xxx失败而中止整体构建，除非你显式检查。

第二步，如果 buildconf 里有这个参数，那就查链接：

docker run --rm --entrypoint ldd ffmpeg:6.1 /usr/local/bin/ffmpeg | grep x264

找不到 libx264.so 的话，是运行时缺库，多半是多阶段构建时没把对应的 so 拷过来，或者 ldconfig 没跑。补上RUN ldconfig，或者在 Dockerfile 里加/usr/local/lib到/etc/ld.so.conf.d/。

第三步，还有一种情况：库在，但版本不匹配。libx264.so.164和编译时链接的libx264.so.163对不上，报undefined symbol。这就是前面提过的运行时包版本必须和构建阶段一致。

三步走完基本能定位。我现在的习惯是在 Dockerfile 最后加一行自检：

RUN ffmpeg -hide_banner -encoders | grep -q libx264 || (echo "libx264 missing" && exit 1)

构建时就失败，比跑到生产才发现好一万倍。

7.2 输出文件的属主是 root，后续流程全挂

前面说过用-u解决。但有个变体情况容易被忽略：如果你挂载的宿主机目录本身权限是 755 且属主是某个特定用户，容器里用另一个 UID 跑就写不进去，报Permission denied。这时候不要急着chmod 777，而是查清楚实际运行的 UID 和目标目录属主是否匹配：

docker run --rm -u "$(id -u):$(id -g)" \ -v /data/media/out:/work/out \ --entrypoint id ffmpeg:6.1 ls -ld /data/media/out

两边的 UID 对上了就行。对不上，要么调-u参数，要么调目录属主，不要无脑放宽权限。

7.3 容器被杀，日志里什么都没有

这个坑的经典表现是：任务跑了两个小时，突然容器消失，docker ps -a里状态是Exited (137)，日志最后一行停在某帧。137 就是 128 + 9，SIGKILL，典型原因是 OOM。

排查要看两个地方：

docker inspect <container> --format '{{.State.OOMKilled}}' dmesg | tail -20

第一个输出true就是内存超了。第二个能在宿主机层面看到 OOM killer 的记录。FFmpeg 在处理大分辨率素材（4K 以上）、或者用了复杂滤镜链（比如大量叠加、缩放、降噪）时，内存占用会比预期高得多，尤其是有多少线程就分多少帧缓冲。

解决办法是提高--memory，或者降低单任务线程数，或者分片处理。我现在的做法是给 4K 素材单独分配更高的内存限额，不要和 1080p 任务混在一个配额里。

7.4 时间戳漂移与精确定位

用容器做片段截取时，遇到过一个挺隐蔽的问题：容器内时区默认是 UTC，某些涉及时间戳的滤镜（比如drawtext打时间、-metadata写日期）会把时间写成 UTC，跟本地时间差几个小时。

这个问题解决起来简单，加个环境变量：

docker run --rm -e TZ=Asia/Shanghai ...

但要注意基础镜像里得有 tzdata，slim 镜像通常没装，TZ设了也不生效。稳妥做法是在构建时apt-get install tzdata，或者在运行时把宿主机的/etc/localtime和/etc/timezone挂进去。

另一个相关问题是-ss的精确定位。放在-i之前的-ss是快速定位，跳转到最近的关键帧，速度极快但位置可能不准；放在-i之后是精确解码定位，慢但准确。做片段截取时如果用错位置，切出来的起点会偏移零点几秒，对需要精确对齐的场景（比如按时间码切分）是不能接受的。

这个跟容器没关系，但我在容器化的批量脚本里踩过一次，因为截取脚本里-ss的位置是在两种写法之间改来改去的，某次改动后没测。教训是：涉及截取精度的脚本，改完必须拿一个已知时间码的样本验一遍。

8. 一些让这套方案更省心的做法

讲几个我在长期使用中固化下来的习惯，不一定适合所有人，但能少踩点坑。

镜像打两个 tag，一个是版本号一个是 latest。生产环境引用版本号 tag，比如ffmpeg:6.1.1，不引用 latest。latest 会随构建变化，某天重新构建一次，行为就可能不同，这种非确定性在生产里是大忌。latest 只用来做本地试验。

把常用参数封成脚本挂在镜像里。我把几套固定参数（比如"归档用"、"预览用"、"网络分发用"）写成 shell 脚本，构建时 COPY 进镜像。运行时直接docker run ... 镜像 -f /opt/presets/archive.sh，省得每次敲一长串参数还敲错。这招在多个人协作时特别有效，参数统一了，输出质量也统一了。

定期重建镜像。基础镜像会更新安全补丁，我的做法是每月重建一次，重建时顺手跑一遍那几条自检命令（编码器列表、硬件加速可用性），确认没退化再推到内部仓库。

日志别只写文件。容器的标准输出是日志的最佳落点，docker logs收集、或者接日志采集都能直接拿到。如果非要写文件，挂载出来，别留在容器可写层里，否则容器一删日志就没了，出问题无从查起。

给长任务设明确的超时。转码任务卡死的情况确实存在（比如源文件是网络流、读到一半断了），脚本层面加个超时保护，超时后杀掉并标记失败，比挂在那里几个小时占资源强。shell 里用timeout命令，或者在编排层设--stop-timeout配合外部监控。

最后说个我自己的体会：这套东西的价值不在于"用了 Docker 显得现代"，而在于它把一个原本靠记忆和手工维护的环境，变成了一份可读、可版本控制、可复现的文本。出了问题，你能查到当时用的是哪个版本、哪套参数；要换机器，拿那份文件重新构建一遍就行。真正省下来的时间，是那些原本花在"为什么这台机器上又不对了"上面的时间。