1. 概述
依赖管理是软件工程中至关重要的一环。在 Python 生态中，多年来出现了多种改进依赖管理的工具。**Poetry** 就是其中一种，它提供了一种更简洁、统一的方式来管理项目依赖，而无需依赖多个工具。
本文将介绍 Poetry 的基本使用方法，并演示如何在 Docker 容器中集成 Poetry 来构建和运行 Python 项目。
2. Poetry 依赖管理工具
Poetry 是一个专为简化 Python 依赖管理而设计的工具。它不依赖传统的 requirements.txt、setup.cfg 或 Pipfile，而是仅使用一个统一的 TOML 配置文件：pyproject.toml。
这个文件中包含了项目的所有依赖和构建配置，通过 poetry 命令即可完成项目的构建、测试和运行。可以说，它的设计灵感来源于 Rust 的 Cargo。
2.1. 基本使用
你可以通过 cURL 从官方安装 Poetry：
$ curl -sSL https://install.python-poetry.org | python3 -
创建一个新项目：
$ poetry new news-aggregator
添加依赖：
$ poetry add scrapy feedreader
查看 pyproject.toml 文件内容：
[tool.poetry]
name = "news-aggregator"
version = "0.1.0"
description = ""
authors = ["Your Name <your.name@example.com>"]
readme = "README.md"
[tool.poetry.dependencies]
python = "^3.12"
scrapy = "^2.11.2"
feedreader = "^0.3.1"
[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
对于已有项目，只需执行以下命令即可安装依赖：
$ poetry install && poetry sync
卸载依赖：
$ poetry remove feedreader && poetry sync
项目目录结构如下：
.
├── Dockerfile
├── main.py
├── news_aggregator
│ └── __init__.py
├── poetry.lock
├── pyproject.toml
├── README.md
└── tests
└── __init__.py
进入虚拟环境：
$ poetry shell
构建项目：
$ poetry build
Poetry 的使用流程相比传统的 pip + virtualenv 更加简洁高效，但将其集成到 Docker 中时，还需要注意一些细节。
3. 在 Docker 中使用 Poetry
本节将介绍如何将 Poetry 项目容器化，并构建一个可部署的 Docker 镜像。
3.1. Dockerfile 初步设置
我们从 Python 官方镜像开始构建：
FROM python:3.12.6-slim-bookworm
设置环境变量：
# Python
ENV PYTHONFAULTHANDLER=1 \
PYTHONUNBUFFERED=1 \
PYTHONHASHSEED=random \
PIP_NO_CACHE_DIR=off \
PIP_DISABLE_PIP_VERSION_CHECK=on \
PIP_DEFAULT_TIMEOUT=100
# Poetry
ENV POETRY_NO_INTERACTION=1 \
POETRY_VIRTUALENVS_CREATE=false \
POETRY_CACHE_DIR='/var/cache/pypoetry' \
POETRY_HOME='/usr/local' \
POETRY_VERSION=1.8.3
ENV YOUR_ENV=${YOUR_ENV}
⚠️ 注意：我们禁用了 Poetry 的虚拟环境功能，因为 Docker 本身已经提供了隔离环境。
3.2. 安装 Poetry 和依赖缓存
先安装 cURL，然后安装 Poetry：
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
RUN curl -sSL https://install.python-poetry.org | python3 -
设置工作目录：
WORKDIR /app
复制依赖文件，以便利用 Docker 缓存机制：
COPY pyproject.toml poetry.lock /app/
3.3. 安装依赖
使用环境变量控制安装生产或开发依赖：
$ poetry install --no-ansi $(test "$ENVIRONMENT" == production && echo "--only=main")
✅ --only=main 表示只安装生产依赖（即 tool.poetry.dependencies 中的依赖）
✅ --no-ansi 用于避免日志输出中的 ANSI 转义码，便于日志查看
3.4. 拷贝项目代码
将项目文件拷贝进容器：
COPY . /app
建议添加 .dockerignore 文件排除不必要的文件，减少构建上下文。
3.5. 启动命令
定义容器启动命令：
CMD ["poetry", "run", "python", "main.py"]
你也可以根据需要修改启动命令，比如运行测试或启动服务。
3.6. 完整 Dockerfile
FROM python:3.12.6-slim-bookworm
# Python
ENV PYTHONFAULTHANDLER=1 \
PYTHONUNBUFFERED=1 \
PYTHONHASHSEED=random \
PIP_NO_CACHE_DIR=off \
PIP_DISABLE_PIP_VERSION_CHECK=on \
PIP_DEFAULT_TIMEOUT=100
# Poetry
ENV POETRY_NO_INTERACTION=1 \
POETRY_VIRTUALENVS_CREATE=false \
POETRY_CACHE_DIR='/var/cache/pypoetry' \
POETRY_HOME='/usr/local' \
POETRY_VERSION=1.8.3
ENV YOUR_ENV=${YOUR_ENV}
RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*
RUN curl -sSL https://install.python-poetry.org | python3 -
WORKDIR /app
COPY pyproject.toml poetry.lock /app/
COPY . /app
CMD ["poetry", "run", "python", "main.py"]
3.7. 构建与运行容器
构建镜像：
$ docker build -t news-aggregator .
运行容器：
$ sudo docker run -d --name instance-1 -e ENVIRONMENT=production news-aggregator
4. 小结
本文介绍了 Poetry 这一现代化的 Python 依赖管理工具，并演示了如何将其集成到 Docker 容器中。通过一个简洁的 Dockerfile，我们实现了项目依赖的高效管理与部署。
✅ Poetry 简化了依赖管理流程
✅ Docker 提供了可靠的部署环境
✅ 二者结合可以构建出结构清晰、易于维护的 Python 项目
如果你正在寻找一个现代化、统一化的 Python 项目管理方式，Poetry + Docker 是一个非常值得尝试的组合。