Docker部署FastAPI报错uvicorn未找到及相关问题求助

1. 解决uvicorn找不到的问题 #

你的问题出在Docker容器的环境变量PATH未包含虚拟环境的可执行文件路径。Docker中每个RUN命令都是独立shell会话，虚拟环境的激活状态不会延续到后续的CMD或RUN命令。

有三种可行解决方式：

方式一：使用虚拟环境内uvicorn的绝对路径修改CMD #

替换原CMD为：

CMD [".venv/bin/uvicorn", "main:app", "--host", "0.0.0.0", "--port", "4001"]

注意：--reload在生产容器中不建议使用，开发环境保留时可能因文件权限出现异常。

方式二：将虚拟环境bin目录加入系统PATH #

在Dockerfile中添加环境变量配置，确保后续命令能找到虚拟环境内的可执行文件：

# 创建虚拟环境后添加
ENV PATH="/iseProject/.venv/bin:$PATH"

# 后续pip安装可简化，无需手动激活虚拟环境
RUN python -m pip install --upgrade pip && \
    python -m pip install multidict && \
    pip install -r requirements.txt

# 原CMD保持不变
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "4001"]

方式三：移除虚拟环境（推荐） #

Docker容器本身已是隔离运行环境，无需额外使用Python虚拟环境，直接安装依赖到系统Python即可简化配置：

# 删除创建虚拟环境和激活的步骤
# RUN python3 -m venv .venv
# RUN . .venv/bin/activate && ...

# 直接安装依赖
RUN python -m pip install --upgrade pip && \
    python -m pip install multidict && \
    pip install -r requirements.txt

2. 添加.env文件到容器 #

要让.env文件出现在容器中，需完成两步：

• 调整Dockerfile配置：
  如果需要通过构建参数指定.env路径，使用：

  ARG ENV_FILE=.env
  COPY $ENV_FILE .env
  

  若固定使用项目根目录的.env，直接简化为：

  COPY .env .
  

• 检查.dockerignore文件：
  确保文件中没有排除.env，如果有类似.env的行，需删除或注释，否则COPY命令会忽略该文件。

3. 优化镜像构建缓存 #

当前Dockerfile先COPY . .再安装依赖，导致任何代码修改都会触发重新安装依赖。优化核心是先复制依赖清单，安装依赖，最后复制项目代码，仅当requirements.txt变化时才会重新执行依赖安装，充分利用Docker构建缓存。

优化后的Dockerfile示例：

FROM python:3.11-alpine

# 安装构建依赖，完成后可清理以减小镜像体积
RUN apk update --update-cache && \
    apk add --no-cache gcc build-base libpq rust cargo libffi-dev openssl-dev python3-dev && \
    # 可选：清理构建依赖，减小镜像大小
    apk del gcc build-base rust cargo

WORKDIR /iseProject

# 先复制requirements.txt，触发缓存
COPY requirements.txt .

# 安装依赖（无需虚拟环境）
RUN python -m pip install --upgrade pip && \
    python -m pip install multidict && \
    pip install -r requirements.txt

# 最后复制项目所有文件
COPY . .

# 添加.env文件
COPY .env .

EXPOSE 4001
ENV NAME World

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

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