Docker构建时python setup.py egg_info执行失败，安装measurement遇版本冲突

之前Docker构建Python项目完全正常，没对项目做任何改动，现在构建失败。错误出在安装measurement==3.2.0环节，具体表现为python setup.py egg_info执行失败（退出码1），根源是sphinxcontrib.applehelp与sphinx存在版本冲突。

相关Docker代码片段 #

# Install Python dependencies
COPY requirements.txt /app/
WORKDIR /app
#RUN pip install --upgrade setuptools
RUN pip install --upgrade pip
RUN pip install -r requirements.txt

错误日志 #

#0 24.46 Collecting measurement==3.2.0
#0 24.48   Downloading measurement-3.2.0.tar.gz (12 kB)
#0 24.49   Preparing metadata (setup.py): started
#0 30.54   Preparing metadata (setup.py): finished with status 'error'
#0 30.55   error: subprocess-exited-with-error
#0 30.55   
#0 30.55   × python setup.py egg_info did not run successfully.
#0 30.55   │ exit code: 1
#0 30.55   ╰─> [14 lines of output]
#0 30.55       Traceback (most recent call last):
#0 30.55         File "<string>", line 2, in <module>
#0 30.55         File "<pip-setuptools-caller>", line 34, in <module>
#0 30.55         File "/tmp/pip-install-uis_8hdi/measurement_709a216af0574a738b280207cf3f2a2e/setup.py", line 4, in <module>
#0 30.55           setup(use_scm_version=True)
#0 30.55         File "/usr/local/lib/python3.8/site-packages/setuptools/__init__.py", line 152, in setup
#0 30.55           _install_setup_requires(attrs)
#0 30.55         File "/usr/local/lib/python3.8/site-packages/setuptools/__init__.py", line 147, in _install_setup_requires
#0 30.55           dist.fetch_build_eggs(dist.setup_requires)
#0 30.55         File "/usr/local/lib/python3.8/site-packages/setuptools/dist.py", line 785, in fetch_build_eggs
#0 30.55           resolved_dists = pkg_resources.working_set.resolve(
#0 30.55         File "/usr/local/lib/python3.8/site-packages/pkg_resources/__init__.py", line 777, in resolve
#0 30.55           raise VersionConflict(dist, req).with_context(dependent_req)
#0 30.55       pkg_resources.ContextualVersionConflict: (sphinxcontrib.applehelp 1.0.3 (/tmp/pip-install-uis_8hdi/measurement_709a216af0574a738b280207cf3f2a2e/.eggs/sphinxcontrib.applehelp-1.0.3-py3.8.egg), Requirement.parse('sphinxcontrib-applehelp'), {'sphinx'})
#0 30.55       [end of output]
#0 30.55   
#0 30.55   note: This error originates from a subprocess, and is likely not a problem with pip.
#0 30.56 error: metadata-generation-failed
#0 30.56 
#0 30.56 × Encountered error while generating package metadata.
#0 30.56 ╰─> See above for output.
#0 30.56 
#0 30.56 note: This is an issue with the package mentioned above, not pip.
#0 30.56 hint: See above for details.

解决方案 #

• 锁定兼容依赖版本：在requirements.txt中添加明确的版本约束，解决命名和版本冲突：

  sphinx<7.0.0
  sphinxcontrib-applehelp>=1.0.4
  

  旧版sphinxcontrib.applehelp（1.0.3）使用下划线命名，而新版sphinx要求短横线命名的sphinxcontrib-applehelp，1.0.4及以上版本已统一命名格式。

• 升级measurement版本：如果项目允许，将requirements.txt中的measurement==3.2.0改为measurement>=3.2.0或更新的稳定版本，新版本大概率修复了构建依赖问题。

• 提前安装兼容依赖：修改Dockerfile，先安装冲突的兼容版本，再安装项目依赖：

  # Install Python dependencies
  COPY requirements.txt /app/
  WORKDIR /app
  RUN pip install --upgrade pip
  RUN pip install sphinx<7.0.0 sphinxcontrib-applehelp>=1.0.4
  RUN pip install -r requirements.txt
  

• 使用固定版本基础镜像：如果之前用的是python:latest这类浮动版本镜像，换成固定版本比如python:3.8-slim-bullseye，避免基础镜像更新导致的依赖环境变化。

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