Docker容器启动报错：uvicorn可执行文件未在$PATH中找到

核心错误原因 #

1. COPY路径语法错误：Dockerfile第二阶段的COPY指令中，目标路径写成了{PYROOT}/，正确的变量引用格式应为${PYROOT}/，这导致base阶段安装的依赖未复制到正确的/pyroot目录，容器启动时PATH中找不到uvicorn可执行文件。
2. Pipenv安装参数冲突：使用pipenv install --system时，PIP_USER=1不会生效——--system参数会强制将包安装到系统Python环境，而非你指定的PYROOT用户目录，导致base阶段的依赖并未写入/pyroot，即使路径正确也复制不到有效内容。

修正方案 #

方案一：安装到用户目录（保留PYROOT配置） #

调整Pipenv安装命令，去掉--system参数，让依赖安装到PYROOT目录，同时修正COPY路径：

FROM python:3.9-alpine AS base

ENV PYROOT /pyroot
ENV PYTHONUSERBASE ${PYROOT}
ENV PATH=${PATH}:${PYROOT}/bin

RUN pip install pipenv
COPY Pipfile* ./
RUN PIP_USER=1 pipenv install --deploy --ignore-pipfile

FROM python:3.9-alpine

ENV PYROOT /pyroot
ENV PYTHONUSERBASE ${PYROOT}
ENV PATH=${PATH}:${PYROOT}/bin

RUN addgroup -S myapp && adduser -S -G myapp user -u 1234
COPY --chown=myapp:user --from=base ${PYROOT}/ ${PYROOT}/

RUN mkdir -p /usr/src/app/app
WORKDIR /usr/src/app

COPY --chown=myapp:user app ./app
COPY --chown=myapp:user main.py ./
USER user

CMD ["uvicorn", "main:app","--host", "0.0.0.0", "--port", "8080"]

方案二：安装到系统环境（简化配置） #

如果不需要用户目录隔离，直接将base阶段的系统Python依赖复制到第二阶段：

FROM python:3.9-alpine AS base

RUN pip install pipenv
COPY Pipfile* ./
RUN pipenv install --system --deploy --ignore-pipfile

FROM python:3.9-alpine

# 复制base阶段的系统依赖包和可执行文件
COPY --from=base /usr/local/lib/python3.9/site-packages /usr/local/lib/python3.9/site-packages
COPY --from=base /usr/local/bin /usr/local/bin

RUN addgroup -S myapp && adduser -S -G myapp user -u 1234

RUN mkdir -p /usr/src/app/app
WORKDIR /usr/src/app

COPY --chown=myapp:user app ./app
COPY --chown=myapp:user main.py ./
USER user

CMD ["uvicorn", "main:app","--host", "0.0.0.0", "--port", "8080"]

验证步骤 #

重新构建并运行容器：

sudo docker build -t myapp:latest . && sudo docker run --name testapp -p 8080:8080 myapp:latest

（注：原运行命令仅写-p 8080会随机分配主机端口，调整为8080:8080便于直接通过主机8080端口访问服务）

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