Python Docker镜像中OpenCV调用FFMPEG编解码器失败求助

问题分析 #

报错里的codec_id=27对应H.264编码器，pip默认安装的opencv-python/opencv-contrib-python预编译版本通常未启用系统FFmpeg的H.264编码支持，加上python-slim镜像自带的FFmpeg组件不全，导致无法找到编码器。

解决方案 #

1. 替换基础镜像并补充编码依赖 #

python-slim镜像的FFmpeg缺少H.264编码所需的libx264库，换成非slim的Python基础镜像，并安装完整编码组件：

# 替换为带完整系统库的基础镜像
FROM python:3.9-bullseye

# 安装FFmpeg及H.264编码依赖
RUN apt-get update && apt-get install -y ffmpeg libsm6 libxext6 libx264-dev postgresql-server-dev-all

2. 从源码编译OpenCV（强制启用FFmpeg/H.264支持） #

如果pip预编译包仍无法加载编码器，直接从源码编译OpenCV，确保绑定系统FFmpeg和libx264：

# 安装编译依赖
RUN apt-get install -y build-essential cmake git libgtk2.0-dev pkg-config libavcodec-dev libavformat-dev libswscale-dev

# 克隆指定版本的OpenCV及扩展库
RUN git clone --depth 1 --branch 4.5.5 https://github.com/opencv/opencv.git && \
    git clone --depth 1 --branch 4.5.5 https://github.com/opencv/opencv_contrib.git

# 编译并安装OpenCV
RUN mkdir -p opencv/build && cd opencv/build && \
    cmake -D CMAKE_BUILD_TYPE=RELEASE \
          -D CMAKE_INSTALL_PREFIX=/usr/local \
          -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
          -D WITH_FFMPEG=ON \
          -D WITH_X264=ON \
          -D BUILD_opencv_python3=ON \
          -D PYTHON3_EXECUTABLE=$(which python3) \
          -D PYTHON3_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
          -D PYTHON3_PACKAGES_PATH=$(python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())") \
          .. && \
    make -j$(nproc) && \
    make install

# 清理编译文件，减小镜像体积
RUN rm -rf opencv opencv_contrib && \
    apt-get purge -y build-essential cmake git && \
    apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*

3. 调整Python依赖安装逻辑 #

使用编译版OpenCV时，需跳过requirements.txt中的opencv相关包，避免覆盖编译版本：

RUN pip install --upgrade pip && \
    grep -v -e opencv requirements.txt | pip install --no-cache-dir -r /dev/stdin && \
    pip install --no-cache-dir onnxruntime-gpu==1.14.0

4. 验证编码器是否可用 #

在容器内运行以下代码，确认H.264编码器已加载：

import cv2
print([cv2.videoio_registry.getEncoderName(codec) for codec in cv2.videoio_registry.getEncoders() if '264' in cv2.videoio_registry.getEncoderName(codec)])

若输出包含'H264'或'avc1'，说明编码器正常可用。

完整修改后的Dockerfile示例 #

FROM python:3.9-bullseye

# 安装基础依赖与编码库
RUN apt-get update && apt-get install -y \
    ffmpeg \
    libsm6 \
    libxext6 \
    libx264-dev \
    postgresql-server-dev-all

WORKDIR /app/ai_model

COPY requirements.txt .

# 安装Python依赖（排除opencv）
RUN pip install --upgrade pip && \
    grep -v -e opencv requirements.txt | pip install --no-cache-dir -r /dev/stdin && \
    pip install --no-cache-dir onnxruntime-gpu==1.14.0

# 编译安装带FFmpeg/H.264支持的OpenCV
RUN apt-get install -y \
    build-essential \
    cmake \
    git \
    libgtk2.0-dev \
    pkg-config \
    libavcodec-dev \
    libavformat-dev \
    libswscale-dev && \
    git clone --depth 1 --branch 4.5.5 https://github.com/opencv/opencv.git && \
    git clone --depth 1 --branch 4.5.5 https://github.com/opencv/opencv_contrib.git && \
    mkdir -p opencv/build && cd opencv/build && \
    cmake -D CMAKE_BUILD_TYPE=RELEASE \
          -D CMAKE_INSTALL_PREFIX=/usr/local \
          -D OPENCV_EXTRA_MODULES_PATH=../../opencv_contrib/modules \
          -D WITH_FFMPEG=ON \
          -D WITH_X264=ON \
          -D BUILD_opencv_python3=ON \
          -D PYTHON3_EXECUTABLE=$(which python3) \
          -D PYTHON3_INCLUDE_DIR=$(python3 -c "from distutils.sysconfig import get_python_inc; print(get_python_inc())") \
          -D PYTHON3_PACKAGES_PATH=$(python3 -c "from distutils.sysconfig import get_python_lib; print(get_python_lib())") \
          .. && \
    make -j$(nproc) && \
    make install && \
    rm -rf opencv opencv_contrib && \
    apt-get purge -y build-essential cmake git && \
    apt-get autoremove -y && \
    rm -rf /var/lib/apt/lists/*

COPY . .

EXPOSE 8080

CMD ["python", "app.py"]

内容的提问来源于stack exchange，提问作者Jrneliodias