Docker中OpenCV用H264(avc1)编码保存视频报错：找不到编码器

核心原因 #

报错「Could not find encoder for codec_id=27」说白了就是OpenCV编译时没正确关联FFmpeg的libx264编码器——哪怕系统里的FFmpeg自己能用libx264编码，只要OpenCV编译过程没启用FFmpeg支持，或者没检测到libx264，就会出这个问题。

分步解决步骤 #

1. 先确认OpenCV编译配置是否正确 #

运行以下Python代码查看OpenCV的编译选项：

import cv2
print(cv2.getBuildInformation())

重点检查这几项：

• FFmpeg: YES（必须显示YES，且下方要出现libx264相关条目）
• HAVE_FFMPEG: YES
• HAVE_LIBX264: YES

如果以上项显示NO，说明OpenCV编译时没关联到FFmpeg的libx264，必须重新编译OpenCV。

2. 重新编译OpenCV的正确流程（Docker环境） #

步骤1：安装完整依赖（必须包含libx264开发包）

apt-get update && apt-get install -y libx264-dev libavcodec-dev libavformat-dev libswscale-dev

如果是自定义编译FFmpeg，编译时必须添加--enable-libx264 --enable-gpl参数，且要将FFmpeg安装到系统可识别的路径（比如/usr/local）。

步骤2：编译OpenCV时明确指定FFmpeg参数

如果是自定义编译的FFmpeg，cmake命令要指定FFmpeg的安装目录，确保OpenCV能检测到：

cmake -D CMAKE_BUILD_TYPE=RELEASE \
      -D CMAKE_INSTALL_PREFIX=/usr/local \
      -D WITH_FFMPEG=ON \
      -D FFMPEG_DIR=/usr/local/ffmpeg \  # 替换为你的FFmpeg实际安装目录
      -D WITH_LIBX264=ON \
      -D BUILD_EXAMPLES=OFF \
      -D BUILD_TESTS=OFF \
      ..

如果是用仓库安装的FFmpeg，直接添加-D WITH_FFMPEG=ON -D WITH_LIBX264=ON即可。

步骤3：重新编译并安装

make -j$(nproc)
make install
ldconfig

3. 更换fourcc参数尝试 #

别局限于'avc1'，试试以下几种写法：

• cv2.VideoWriter_fourcc(*'H264')
• cv2.VideoWriter_fourcc(*'X264')
• 直接使用数字编码0x31363248（对应H264）

测试代码示例：

import cv2

# 可替换为本地视频文件路径
cap = cv2.VideoCapture(0)
width = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
height = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))

# 尝试X264编码
fourcc = cv2.VideoWriter_fourcc(*'X264')
out = cv2.VideoWriter('output.mp4', fourcc, 25.0, (width, height))

if not out.isOpened():
    print("VideoWriter初始化失败")
else:
    print("VideoWriter初始化成功")

4. Docker环境额外注意事项 #

• 编译时容器内依赖必须完整，不要遗漏libx264-dev这类开发包
• 如果是多阶段构建镜像，要确保编译阶段的OpenCV产物正确复制到运行镜像中，避免运行时找不到库
• 运行Python时，确认加载的是自定义编译的OpenCV而非系统默认版本——可通过print(cv2.__file__)查看库路径

常见坑点 #

• 自定义编译FFmpeg时未添加--enable-shared参数，导致OpenCV无法链接动态库
• OpenCV编译时，cmake日志中需出现「Found libx264」的提示，无提示则说明未检测到libx264
• 部分系统仓库的FFmpeg版本过低，易出现兼容性问题，建议自定义编译3.4以上版本的FFmpeg

内容的提问来源于stack exchange，提问作者l.diazborg