以下是一份 Poetry 完全指南，涵盖从安装到高级功能的全面教程，结合最佳实践和实用技巧：

点赞标记，明天就能用上这几个技巧！

1. 安装 Poetry

系统级安装（推荐）

# Linux/macOS
curl -sSL https://install.python-poetry.org | python3 -

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | py -

验证安装

poetry --version# 输出示例: Poetry (version 1.8.0)

配置中国镜像加速

poetry config repo.pypi.url https://pypi.tuna.tsinghua.edu.cn/simple/

️2. 项目管理

创建新项目

poetry new my-project && cd my-project

生成目录结构：

my-project/
├── pyproject.toml# 核心配置文件
├── README.md
├── src/
│└── my_project/
│└── __init__.py
└── tests/
└── test_my_project.py

初始化现有项目

cd existing-project
poetry init# 交互式生成 pyproject.toml

3. 依赖管理

安装依赖

poetry install# 安装所有依赖（含开发依赖）
poetry install --no-dev# 仅生产依赖

添加/移除依赖

# 生产依赖
poetry add requests numpy@^1.24# 指定版本约束

# 开发依赖（测试/文档等）
poetry add --group dev pytest black

# 移除依赖
poetry remove pandas

锁定依赖版本

poetry lock# 生成 poetry.lock 确保版本一致性

4. 虚拟环境管理

自动创建环境（默认）

poetry env use python3.10# 指定Python版本
poetry shell# 激活虚拟环境

项目内建环境（推荐）

poetry config virtualenvs.in-project true# 创建 .venv 在项目内

常用命令

poetry env info# 查看环境信息
poetry env list# 列出所有环境
poetry env remove 3.10# 删除环境

5. 依赖分组（高级功能）

分组管理（测试/文档/性能）

# pyproject.toml
[tool.poetry.group.test.dependencies]
pytest = "^7.4"
coverage = "*"

[tool.poetry.group.docs.dependencies]
sphinx = "^7.0"

安装指定组

poetry install --with test,docs# 安装多组依赖
poetry add --group perf pyinstrument# 添加新组

6. 打包与发布

构建包

poetry build# 生成 dist/ 目录下的 .whl 和 .tar.gz

发布到 PyPI

# 配置 API Token
poetry config pypi-token.pypi your-token-here

# 发布
poetry publish

发布到私有仓库

# pyproject.toml
[[tool.poetry.source]]
name = "private"
url = "https://private-repo.example/simple"

poetry publish -r private

️7. 进阶配置

脚本别名

# pyproject.toml
[tool.poetry.scripts]
start = "my_project.main:run_app"
bench = "python benchmarks/main.py"

运行：poetry run start

多环境配置

# 条件依赖 (Windows专用)
pathlib2 = { version = "*", markers = "sys_platform == 'win32'" }

源码依赖

[tool.poetry.dependencies]
my-lib = { git = "https://github.com/user/repo.git", branch = "main" }

8. 故障排查

常见问题解决

# 重置环境
poetry env remove --all
poetry cache clear --all pypi
poetry lock --no-cache
poetry install

# 依赖冲突诊断
poetry show --tree
poetry show --latest | grep -v up-to-date

✅9. 最佳实践

1. 锁定文件必提交：将 poetry.lock 加入 Git 确保团队版本一致
2. 版本约束规范：

• ^1.2.3 = 1.x.x (x≥2.3)
• ~1.2.3 = 1.2.x (x≥3)
• >=4.5,<5.0

3. CI/CD 集成示例：

# GitHub Actions 配置
- name: Install Poetry
run: pipx install poetry
- name: Install dependencies
run: poetry install --no-interaction
- name: Run tests
run: poetry run pytest

10. 工作流示例

11. 学习资源

1. 官方文档
2. Cheat Sheet：

# 查看已安装包
poetry show

# 更新所有依赖
poetry update

# 导出 requirements.txt
poetry export -f requirements.txt --output requirements.txt

提示：结合 uv 加速安装：
poetry export -f requirements.txt | uv pip install -r /dev/stdin

都看到这里了， 记得帮忙一键三连， 点赞、评论、收藏、关注
不要只收藏，我要点赞！点赞！点赞！谢谢！！！