如何在多阶段Docker镜像中使用OpenCV？

近期尝试用多阶段Dockerfile构建视频目标检测应用（Python+TensorFlow）的镜像时遇到问题：简单示例运行正常，但部署自有应用时出现模块找不到的错误。

原Dockerfile #

FROM python:3-slim AS base

WORKDIR /objectDetector

COPY detect_objects.py .
COPY detector.py .
COPY requirements.txt .
ADD data /objectDetector/data/
ADD models /objectDetector/models/

RUN apt-get update && \
    apt-get install protobuf-compiler -y && \
    apt-get install ffmpeg libsm6 libxext6 -y && \
    apt-get install gcc -y

RUN pip3 install update && python3 -m pip install --upgrade pip
RUN pip3 install tensorflow-cpu==2.9.1
RUN pip3 install opencv-python==4.6.0.66
RUN pip3 install opencv-contrib-python

WORKDIR /objectDetector/models/research
RUN protoc object_detection/protos/*.proto --python_out=.
RUN cp object_detection/packages/tf2/setup.py .
RUN python -m pip install .
RUN python object_detection/builders/model_builder_tf2_test.py

WORKDIR /objectDetector/models/research
RUN pip3 install wheel && pip3 wheel . --wheel-dir=./wheels 

FROM python:3-slim
RUN pip3 install update && python3 -m pip install --upgrade pip
COPY --from=base /objectDetector /objectDetector
WORKDIR /objectDetector
RUN pip3 install --no-index --find-links=/objectDetector/models/research/wheels -r requirements.txt

运行错误 #

root@3f062f9a5d64:/objectDetector# python detect_objects.py 
Traceback (most recent call last):
  File "/objectDetector/detect_objects.py", line 3, in <module>
    import cv2
ModuleNotFoundError: No module named 'cv2'

原因分析 #

多阶段构建中，第二阶段的python:3-slim是全新镜像，第一阶段通过pip安装的OpenCV、TensorFlow等依赖包存储在第一阶段Python的site-packages目录下。你仅复制了/objectDetector目录，未将这些已安装的依赖迁移到第二阶段的Python环境；同时第二阶段仅通过requirements.txt从指定wheel目录安装部分包，而OpenCV的wheel并未生成在该目录，导致运行时找不到cv2模块。

修复方案 #

方式一：直接复制第一阶段的Python环境

这种方式简单直接，可完整迁移所有已安装依赖：

FROM python:3-slim AS base

WORKDIR /objectDetector

COPY detect_objects.py .
COPY detector.py .
COPY requirements.txt .
ADD data /objectDetector/data/
ADD models /objectDetector/models/

RUN apt-get update && \
    apt-get install protobuf-compiler -y && \
    apt-get install ffmpeg libsm6 libxext6 -y && \
    apt-get install gcc -y

RUN python3 -m pip install --upgrade pip
RUN pip3 install tensorflow-cpu==2.9.1
RUN pip3 install opencv-python==4.6.0.66
RUN pip3 install opencv-contrib-python

WORKDIR /objectDetector/models/research
RUN protoc object_detection/protos/*.proto --python_out=.
RUN cp object_detection/packages/tf2/setup.py .
RUN python -m pip install .
RUN python object_detection/builders/model_builder_tf2_test.py

# 清理apt缓存减小镜像体积
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

FROM python:3-slim
WORKDIR /objectDetector

# 复制第一阶段的Python依赖包目录
COPY --from=base /usr/local/lib/python3.*/site-packages /usr/local/lib/python3.*/site-packages
# 复制应用代码与模型文件
COPY --from=base /objectDetector /objectDetector

# 安装OpenCV依赖的系统库（slim镜像默认缺失）
RUN apt-get update && \
    apt-get install -y --no-install-recommends ffmpeg libsm6 libxext6 && \
    apt-get clean && rm -rf /var/lib/apt/lists/*

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

方式二：生成所有依赖的wheel包后在第二阶段安装

这种方式遵循多阶段构建“构建/运行依赖分离”原则，可进一步压缩镜像体积：

FROM python:3-slim AS base

WORKDIR /objectDetector

COPY detect_objects.py .
COPY detector.py .
COPY requirements.txt .
ADD data /objectDetector/data/
ADD models /objectDetector/models/

RUN apt-get update && \
    apt-get install protobuf-compiler -y && \
    apt-get install ffmpeg libsm6 libxext6 -y && \
    apt-get install gcc -y

RUN python3 -m pip install --upgrade pip wheel
# 生成所有依赖的wheel包（含OpenCV、TensorFlow）
RUN pip3 wheel -r requirements.txt --wheel-dir=/wheels
# 生成自定义目标检测包的wheel
WORKDIR /objectDetector/models/research
RUN protoc object_detection/protos/*.proto --python_out=.
RUN cp object_detection/packages/tf2/setup.py .
RUN pip3 wheel . --wheel-dir=/wheels

# 清理apt缓存
RUN apt-get clean && rm -rf /var/lib/apt/lists/*

FROM python:3-slim
WORKDIR /objectDetector

# 复制wheel包与应用文件
COPY --from=base /wheels /wheels
COPY --from=base /objectDetector /objectDetector

# 安装系统依赖与Python依赖
RUN apt-get update && \
    apt-get install -y --no-install-recommends ffmpeg libsm6 libxext6 && \
    apt-get clean && rm -rf /var/lib/apt/lists/* && \
    python3 -m pip install --upgrade pip && \
    pip3 install --no-index --find-links=/wheels -r requirements.txt && \
    pip3 install --no-index --find-links=/wheels object-detection && \
    # 清理wheel包减小体积
    rm -rf /wheels

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

注意事项 #

1. 确保requirements.txt包含所有必要依赖，如tensorflow-cpu==2.9.1、opencv-python==4.6.0.66等，否则生成wheel包时会遗漏。
2. 第二阶段必须安装OpenCV依赖的系统库，否则即使安装了Python包，运行时仍会因底层库缺失报错。

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