本文详解如何在heroku上通过docker+poetry正确部署django应用，核心在于禁用poetry默认虚拟环境、确保依赖安装到系统python路径，并优化dockerfile结构以适配heroku非root运行机制。
本文详解如何在heroku上通过docker+poetry正确部署django应用，核心在于禁用poetry默认虚拟环境、确保依赖安装到系统python路径，并优化dockerfile结构以适配heroku非root运行机制。
Heroku容器运行时默认以非root用户执行镜像（详见官方文档），而Poetry默认会创建并激活专属虚拟环境（如 /root/.cache/pypoetry/virtualenvs/...）。当容器以非root用户启动时，该虚拟环境路径不可写或不可访问，且系统级 python 和 pip 命令无法感知其中安装的包——这正是你本地正常、上线后“依赖未安装”的根本原因。
✅ 正确做法：禁用Poetry虚拟环境，直装至系统Python
Poetry提供配置项 virtualenvs.create = false，启用后将跳过虚拟环境创建逻辑，直接将依赖安装到当前Python解释器的 site-packages 目录（即系统环境）。由于Heroku的Docker基础镜像（如 python:3.11-alpine）中Python由root安装，其 site-packages 对所有用户可读，因此非root进程也能正常导入依赖。
修改你的 Dockerfile，关键调整如下：
FROM python:3.11-alpine
WORKDIR /code
ENV PYTHONUNBUFFERED=1
ENV PATH="/root/.local/bin:$PATH"
# 安装Poetry及构建依赖
RUN apk add --no-cache curl postgresql-dev musl-dev \
&& curl -sSL https://install.python-poetry.org | python3 -
# 复制锁文件和配置（必须在poetry install前）
COPY poetry.lock pyproject.toml .
# ⚠️ 关键：禁用虚拟环境 + 一次性安装所有依赖（含当前项目）
RUN poetry config virtualenvs.create false \
&& poetry install --no-root
# 复制全部源码（注意顺序：必须在poetry install之后）
COPY . .
# 可选：显式声明非root用户（增强兼容性与安全性）
USER nobody:nogroup
? 为什么只需一次 poetry install？
原Dockerfile中两次调用（--no-root + 后续无参）是冗余的：第一次已解析 poetry.lock 并安装全部依赖；第二次因无新变更仅尝试安装当前项目（失败于缺失 README.md），且此时虚拟环境已被禁用，无需重复操作。
? 不推荐的做法
- 维护 requirements.txt 并用 pip install -r：违背Poetry单一可信源原则，增加同步负担和版本漂移风险；
- 双Dockerfile（dev/prod）：增加维护复杂度，且未解决根本的权限与路径问题；
- 多阶段构建：对纯Python Web应用收益有限，反而增加构建时间与调试难度。
✅ 验证与最佳实践
-
本地模拟Heroku环境：
docker build -t myapp . && docker run --user 1001:1001 -it myapp python -c "import django; print(django.__version__)"
若成功输出版本号，说明依赖已正确安装至系统路径。
-
heroku.yml 保持简洁：
build: docker: web: backend/Dockerfile run: web: gunicorn core.wsgi:application --bind 0.0.0.0:$PORT -
安全加固建议：
- 显式使用 USER nobody:nogroup（如上所示），避免以root运行应用进程；
- 在 pyproject.toml 中设置 package-mode = false（若无需打包发布），消除Poetry警告。
通过以上调整，你的Django应用将真正实现“一次编写，随处部署”——Poetry管理依赖、Docker封装环境、Heroku可靠运行为一体，无需妥协或绕行。
