AWS CodeBuild构建Docker镜像失败：externally-managed-environment错误排查

几个月前AWS CodeBuild可成功构建目标Dockerfile，但推送新代码变更后构建失败，执行RUN pip3 install --upgrade pip步骤时触发如下错误：

Processing triggers for libc-bin (2.36-9+deb12u7) ...
Removing intermediate container 59eb038789d6
 ---> 4d864f03be13
Step 6/27 : RUN pip3 install --upgrade pip
 ---> Running in 7921c1b93c88
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.
    
    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.
    
    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.
    
    See /usr/share/doc/python3.11/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.
The command '/bin/sh -c pip3 install --upgrade pip' returned a non-zero code: 1

问题原因 #

Debian 12（Bookworm）及后续版本遵循PEP 668规范，默认禁止pip直接修改系统级Python环境，防止和系统包管理器（apt）的依赖关系冲突。之前能正常构建是因为当时使用的mcr.microsoft.com/dotnet/aspnet:8.0基础镜像基于旧版Debian，没有启用这个限制；现在镜像更新到Debian 12后，触发了该保护机制。

解决方案 #

方案1：用apt安装系统包替代pip（推荐，符合系统规范） #

awscli可以通过apt直接安装，无需使用pip。修改Dockerfile中的相关步骤：

将原来的：

RUN pip3 install --upgrade pip
RUN pip3 install --upgrade setuptools && pip3 install awscli

替换为：

RUN apt-get install -y --no-install-recommends awscli

方案2：使用虚拟环境隔离依赖（适合必须用pip安装的场景） #

创建独立的Python虚拟环境，所有pip安装的包都在虚拟环境中，不会影响系统Python：

修改Dockerfile中的步骤：

# 创建并配置虚拟环境
RUN python3 -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

# 安全升级pip并安装依赖
RUN pip3 install --upgrade pip
RUN pip3 install --upgrade setuptools && pip3 install awscli

方案3：强制突破系统限制（不推荐，可能导致系统问题） #

如果必须在系统级安装，可添加--break-system-packages参数强制绕过限制，但可能破坏系统依赖，仅临时应急使用：

RUN pip3 install --upgrade pip --break-system-packages
RUN pip3 install --upgrade setuptools --break-system-packages && pip3 install awscli --break-system-packages

修改后的完整Dockerfile（方案1示例） #

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 80
EXPOSE 443

RUN apt-get update -y && apt-get -y upgrade && \
    apt-get install -y --no-install-recommends python3-pip python3-dev build-essential awscli

COPY Backend/Deploy/entrypoint.sh .
RUN chmod +x entrypoint.sh

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY Backend/Api/Api.csproj Backend/Api/
COPY Shared/Api.DTO/Api.DTO.csproj Shared/Api.DTO/
COPY Backend/Backend.Core/Backend.Core.csproj Backend/Backend.Core/
COPY Backend/Database.Core/Database.Core.csproj Backend/Database.Core/
COPY Backend/Database.Enums/Database.Enums.csproj Backend/Database.Enums/
COPY Shared/Backend.SharedLogic/Backend.SharedLogic.csproj Shared/Backend.SharedLogic/
RUN dotnet restore "Backend/Api/Api.csproj"
COPY . .
WORKDIR "/src/Backend/Api"
RUN dotnet build "Api.csproj" -c Release -o /app/build

FROM build AS publish
RUN dotnet publish "Api.csproj" -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["./entrypoint.sh", "dotnet", "Api.dll"]

内容的提问来源于stack exchange，提问作者Sheharyar S.