对于 Python 开发者来说，Poetry 几乎重新定义了「Python 依赖管理」的体验：一个 pyproject.toml 同时管住依赖、虚拟环境和打包发布，告别 requirements.txt 漂移、virtualenv 散落各处的混乱。本文带你从安装到发布 PyPI，把 Poetry 真正用进日常工程。
一、为什么还需要 Poetry
传统工作流有三个痛点。第一，requirements.txt 只记录顶层依赖，子依赖版本不可控，多人协作经常遇到「在我机器上是好的」。第二，virtualenv 路径散乱，activate 容易忘、容易错。第三，当你想把项目发布成包时，setup.py、setup.cfg、MANIFEST.in 的配置繁琐且容易出错。Poetry 用单一声明文件 + 锁文件 + 内置虚拟环境与发布命令，把这些步骤串成一条流水线。
二、10 分钟上手：安装与初始化
官方推荐用 pipx 把 Poetry 装在独立环境里，避免污染项目依赖。你也可以用官网安装器或 Homebrew。
# 官方推荐：pipx 隔离安装
pipx install poetry
# 官网安装器（通用）
curl -sSL https://install.python-poetry.org | python3 -
# macOS 用户
brew install poetry安装完成后，用 poetry new 生成标准项目骨架，或在已有目录用 poetry init 交互式生成配置。
poetry --version
poetry new my_project # 生成 src/ + tests/ 标准结构
poetry init # 在已有目录交互式生成 pyproject.toml三、依赖管理：pyproject.toml 的核心玩法
3.1 添加与移除依赖（区分运行时 / 开发）
Poetry 1.2 之后用 group 区分依赖类型，main 是运行时依赖，dev 或其他自定义 group 是开发依赖。部署时只装 main 即可。
poetry add requests # 运行时依赖
poetry add -G dev pytest ruff # 开发依赖（group）
poetry add "django>=4.2,<5" # 限定版本区间
poetry remove requests # 移除依赖3.2 锁文件与可重现安装
poetry.lock 把整棵依赖树精确锁定。提交它之后，所有人、CI、生产环境都能装出完全一致的依赖。
poetry lock # 解析依赖并写 poetry.lock
poetry install # 按 lock 安装
poetry install --sync # 与 lock 严格对齐，移除多余包
poetry install --only main # 只装运行时依赖（部署用）| 维度 | pip + requirements | Poetry |
|---|---|---|
| 依赖解析 | 无，顺序安装 | 有向图求解，冲突早暴露 |
| 锁文件 | 需 pip freeze 手写 | poetry.lock 自动生成 |
| 开发/运行分离 | 手动维护多文件 | group 原生支持 |
| 打包发布 | setup.py 手写 | build/publish 一条龙 |
四、虚拟环境：不再手动 activate
Poetry 默认在统一缓存目录创建虚拟环境，你几乎不需要手动 activate。用 poetry run 直接在该环境执行命令，或 poetry shell 进入交互式环境。
poetry env info # 查看当前环境信息
poetry env use 3.12 # 切换 Python 版本
poetry shell # 进入虚拟环境 shell
poetry run python main.py # 无需 activate 直接跑如果你更喜欢把虚拟环境放在项目内的 .venv，可执行 poetry config virtualenvs.in-project true。配合 Dev Container 实战：团队开发环境一次配好 这类可复现方案，本地与远程环境能进一步对齐。
五、打包与发布：从源码到 PyPI
Poetry 把打包和发布也纳入了同一套命令。先 build 生成 sdist 与 wheel，再用 publish 上传，全程无需手写 setup.py。
poetry build # 生成 dist/*.tar.gz 与 *.whl
poetry config pypi-token.pypi <TOKEN>
poetry publish # 上传到 PyPI
poetry publish --build # 先 build 再上传| 发布方式 | 适用场景 | 命令 |
|---|---|---|
| TestPyPI 试发 | 验证元数据是否正确 | poetry publish -r testpypi |
| 正式 PyPI | 公开库上线 | poetry publish |
| 私有源 | 公司内部共享 | poetry config repositories.foo <url> |
六、在 CI 与容器中落地
在 GitHub Actions 实战：从零搭建 CI/CD 流水线 里，用 Poetry 安装依赖并发布是最自然的组合。下面这段工作流在打 release 时自动构建并上传到 PyPI。
name: publish
on:
release:
types: [published]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: "3.12" }
- run: pipx install poetry
- run: poetry install --only main
- run: poetry build
- run: poetry publish
env:
POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}容器化时，利用 Docker 编排 的思路，把 Poetry 装进镜像并只装运行时依赖，能显著减小镜像体积。
FROM python:3.12-slim
ENV POETRY_VERSION=1.8.3 POETRY_VIRTUALENVS_CREATE=false
RUN pip install "poetry==$POETRY_VERSION"
WORKDIR /app
COPY pyproject.toml poetry.lock ./
RUN poetry install --only main --no-root
COPY . .
CMD ["poetry", "run", "python", "main.py"]七、Poetry 与 uv 怎么选
uv 实战：Python 包管理与虚拟环境极速指南 里的 uv 用 Rust 重写，安装速度比 Poetry 快一个数量级，特别适合追求极速 CI 的团队。Poetry 则胜在稳定、功能完整（依赖组、发布、插件生态成熟）。新项目两者都能选，老项目是否迁移要看团队习惯与收益——如果只是想要更快的 install，uv 的 uv pip 也能渐进替换。
八、常见坑与排障
| 现象 | 原因 | 解决 |
|---|---|---|
| 安装慢 | 默认源在国外 | poetry source add 清华/阿里镜像 |
| lock 冲突 | 多人同时改 toml | 先 pull 再 lock，务必提交 lock |
| 找不到私有包 | 私有源未配置 | poetry source add 私有源 |
| 版本解析失败 | 约束过严 | 放宽区间或 poetry lock –no-update |
把 Poetry 接进日常工作流后，依赖一致性、可重现构建和发布效率都会明显提升。建议新项目直接从 poetry new 起步，老项目可以分阶段把 requirements.txt 迁到 pyproject.toml，先享受锁文件带来的确定性，再逐步过渡到完整打包发布流程。
