Article

包管理器 Poetry

更新于：2026-07-13

第一章：Poetry 概述与安装

1.1 Poetry 是什么

概念名称	说明	注意事项
Poetry	一个用于 Python 项目的依赖管理与打包工具，通过单一配置文件 `pyproject.toml` 管理项目元数据、依赖、脚本等	不是 pip 的替代品，而是更高层的项目管理工具，底层仍使用 pip 安装包
pyproject.toml	Poetry 使用的标准配置文件，遵循 PEP 518/621 规范，统一描述项目依赖、构建系统、元数据等	文件必须位于项目根目录；修改后需重新解析依赖（如运行 `poetry install`）
poetry.lock	锁定依赖版本的文件，确保所有环境安装完全一致的依赖树	应提交到版本控制系统；不要手动编辑
虚拟环境自动管理	Poetry 默认为每个项目创建并管理独立的虚拟环境，无需手动调用 venv 或 virtualenv	虚拟环境默认存储在 Poetry 的全局缓存目录中（可通过 `poetry env info` 查看路径）

1.2 Poetry 与 pip / virtualenv / pipenv 对比

工具名称	所属类别	主要用途	与 Poetry 的关键区别	注意事项
pip	包安装器	安装 Python 包	仅负责安装，不管理虚拟环境或项目元数据	需配合 venv 使用才能隔离环境
virtualenv / venv	虚拟环境工具	创建隔离的 Python 环境	仅提供环境隔离，不处理依赖声明或锁定	需手动激活/停用环境
pipenv	依赖+环境管理器	结合 pip 与 virtualenv，使用 Pipfile	功能类似 Poetry，但性能较差、维护活跃度低、不支持 PEP 621	Pipfile 非标准格式，社区逐渐转向 Poetry
Poetry	项目管理与打包工具	统一管理依赖、虚拟环境、构建、发布	遵循现代 Python 标准（PEP 518/621），性能好，功能完整，支持脚本、插件、多依赖组	初学者需理解 `pyproject.toml` 结构

1.3 安装 Poetry

步骤名称	操作细节	注意事项
推荐安装方式（官方脚本）	在终端执行：`curl -sSL https://install.python-poetry.org \| python3 -` 或 `(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content \| python -`	该方式将 Poetry 安装到 `$HOME/.local/bin`（Linux/macOS）或 `%APPDATA%\Python\Scripts`（Windows）；确保该路径已加入系统 PATH
验证安装	执行 `poetry --version`	若提示命令未找到，请检查 PATH 是否包含 Poetry 安装目录
升级 Poetry	执行 `poetry self update`	仅适用于通过官方脚本安装的 Poetry；通过 pip/pipx 安装的需用对应方式升级
替代安装方式（pipx）	先安装 pipx：`pip install pipx`，再执行：`pipx install poetry`	推荐用于已有 pipx 管理习惯的用户；可避免污染全局 Python 环境
不推荐的安装方式（直接 pip install）	`pip install poetry`	可能与项目依赖冲突，因 Poetry 本身依赖特定版本的库；官方明确不推荐

第二章：项目初始化与配置

2.1 创建新项目（`poetry new`）

方法名称	语法	用途	代码示例	注意事项
`poetry new`	`poetry new [项目名] [--src]`	快速创建符合 Poetry 规范的新 Python 项目骨架	`poetry new my_project`	默认将包代码放在与项目同名的顶层目录下；若希望遵循 `src/` 布局（更推荐），需加 `--src` 参数：`poetry new --src my_project`
`poetry new --name`	`poetry new [目录名] --name [包名]`	指定 Python 包模块名称（与目录名不同）	`poetry new my_app_dir --name my_app`	适用于希望项目目录名与导入模块名不一致的场景

生成目录结构：

my_project/
├── pyproject.toml
├── README.rst
├── my_project/
│   └── __init__.py
└── tests/
    ├── __init__.py
    └── test_my_project.py

2.2 初始化现有项目（`poetry init`）

方法名称	语法	用途	代码示例	注意事项
`poetry init`	`poetry init [--name] [--description] [--author] [--python] [--dependency] ...`	在现有目录中交互式生成 `pyproject.toml` 文件	进入已有项目目录后执行：`poetry init`，然后按提示输入项目名称、版本、描述、作者、Python 版本、依赖等	该命令不会移动或修改现有代码文件，仅生成配置文件；适合将旧项目迁移到 Poetry 管理
`poetry init --no-interaction`	`poetry init --no-interaction --name=myproj --python="^3.9"`	非交互式初始化（用于脚本或 CI）	`poetry init --no-interaction --name=legacy_app --python=">=3.8,<3.12"`	必须提供所有必要参数，否则会失败；适合自动化场景

2.3 `pyproject.toml` 配置详解

本小节介绍 pyproject.toml 中的核心配置项。由于该文件是声明式配置而非方法调用，以下以配置项为单位列出。

配置项名称	说明	注意事项
`[tool.poetry]`	Poetry 项目的元数据区块，包含名称、版本、描述等	所有 Poetry 专属配置必须在此区块下
`name`	项目名称（发布到 PyPI 的包名）	必填；应符合 Python 包命名规范（小写、连字符转下划线）
`version`	项目版本号	必填；建议遵循语义化版本（SemVer）如 `"0.1.0"`
`description`	项目简短描述	可选；会显示在 PyPI 页面
`authors`	作者列表，格式为 `["Name <email>"]`	可选但推荐；用于 PyPI 元数据
`license`	项目许可证（如 `"MIT"`）	可选；建议明确指定
`readme`	README 文件路径（如 `"README.md"`）	支持 `.md` 或 `.rst`；若存在会自动包含到分发包中
`homepage`、`repository`、`documentation`	项目相关链接	可选；增强 PyPI 页面信息
`keywords`	关键词列表	有助于 PyPI 搜索
`classifiers`	PyPI 分类器（如 `["Programming Language :: Python :: 3.10"]`）	可选；建议包含 Python 版本支持声明
`packages`	显式指定包路径（当默认发现不满足时）	格式：`{ include = "mypkg" }` 或 `{ include = "mypkg", from = "lib" }`；通常可省略
`[tool.poetry.dependencies]`	项目运行时依赖	使用 `poetry add` 自动写入；Python 版本约束也在此声明，如 `python = "^3.9"`
`[tool.poetry.group.dev.dependencies]`	开发依赖（如 pytest、black）	使用 `poetry add --group dev pytest` 添加；不会包含在生产安装中
`[build-system]`	构建后端声明（Poetry 自动生成）	内容固定为：`requires = ["poetry-core"]` / `build-backend = "poetry.core.masonry.api"`，不要手动修改
`[tool.poetry.scripts]`	定义命令行入口点	例如：`mycli = "myapp.cli:main"`，安装后可在终端直接运行 `mycli`

⚠️ 注意：pyproject.toml 是 TOML 格式，对缩进和引号敏感。字符串建议使用双引号。列表使用方括号，表使用花括号。

第三章：依赖管理

3.1 添加依赖（`poetry add`）

方法名称	语法	用途	代码示例	注意事项
`poetry add`	`poetry add [包名] [选项]`	向项目添加运行时依赖，并更新 `pyproject.toml` 和 `poetry.lock`	`poetry add requests` → 添加最新兼容版本；`poetry add "django>=4.2,<5.0"` → 指定版本约束	默认添加到 `[tool.poetry.dependencies]`；若未指定版本，Poetry 会自动选择兼容当前 Python 版本的最新版
`poetry add --group`	`poetry add --group [组名] [包名]`	将依赖添加到指定依赖组（如开发组）	`poetry add --group dev pytest` 等价于 `poetry add -G dev pytest`	常见组名：dev、test、docs；首次使用某组名时会自动创建该组
`poetry add --optional`	`poetry add --optional [包名]`	添加可选依赖（需在安装时显式启用）	`poetry add --optional redis`；后续通过 `poetry install -E redis` 安装	可选依赖需配合 extras 使用，适用于插件式功能
`poetry add --python`	`poetry add [包名] --python ">=3.9"`	为依赖指定仅在特定 Python 版本下生效	`poetry add dataclasses --python "<3.7"`	适用于兼容性补丁包（如 dataclasses 在 Python <3.7 才需要）
`poetry add --source`	`poetry add --source [源名] [包名]`	从私有源安装包	`poetry add --source my-pypi internal-lib`	需先通过 `poetry source add` 配置源

3.2 删除依赖（`poetry remove`）

方法名称	语法	用途	代码示例	注意事项
`poetry remove`	`poetry remove [包名]`	从主依赖中移除指定包	`poetry remove requests`	同时从 `pyproject.toml` 和 `poetry.lock` 中删除；若包被其他依赖引用，可能仍保留在 lock 文件中
`poetry remove --group`	`poetry remove --group [组名] [包名]`	从指定依赖组中移除包	`poetry remove --group dev pytest`	若组中无其他依赖，该组区块可能被保留为空
`poetry remove --dry-run`	`poetry remove --dry-run [包名]`	预演删除操作，不实际修改文件	`poetry remove --dry-run numpy`	用于检查依赖影响，安全验证

3.3 更新依赖（`poetry update`）

方法名称	语法	用途	代码示例	注意事项
`poetry update`	`poetry update`	更新所有依赖到符合 `pyproject.toml` 约束的最新版本	`poetry update`	会重新解析依赖树并更新 `poetry.lock`；不会修改 `pyproject.toml` 中的版本约束
`poetry update [包名]`	`poetry update [包1] [包2] ...`	仅更新指定包及其子依赖	`poetry update requests urllib3`	适用于局部升级，减少变更范围
`poetry update --dry-run`	`poetry update --dry-run`	预览将要更新的包列表	`poetry update --dry-run`	不修改任何文件，仅输出变更摘要
`poetry update --lock`	`poetry update --lock`	仅更新 `poetry.lock`，不安装到环境	`poetry update --lock`	适用于 CI 中生成新 lock 文件但不部署

⚠️ 注意：poetry update 不同于 pip install --upgrade，它始终尊重 pyproject.toml 中的版本范围。

3.4 锁定依赖（`poetry.lock` 机制）

概念名称	说明	注意事项
`poetry.lock`	锁定文件，记录所有依赖（包括间接依赖）的确切版本、哈希值和来源	必须提交到版本控制系统，确保团队和 CI 环境一致性
生成时机	执行 `poetry install`、`poetry add`、`poetry update` 等命令时自动生成或更新	若 `poetry.lock` 不存在，`poetry install` 会先解析依赖并生成它
内容结构	包含每个包的 name、version、description、category、optional、python-versions、files（含 hash）等	人类可读，但不应手动编辑
与 `pyproject.toml` 关系	`pyproject.toml` 定义允许的版本范围，`poetry.lock` 记录实际选择的版本	修改 `pyproject.toml` 后必须运行 `poetry install` 或 `poetry update` 以同步 lock 文件
锁文件失效	当 `pyproject.toml` 改变且未更新 lock 文件时，Poetry 会警告或拒绝安装	可通过 `poetry lock --no-update` 仅基于现有约束重新生成 lock（不升级）

3.5 依赖组（groups）与开发依赖

概念/方法名称	说明	注意事项
依赖组（Dependency Groups）	Poetry 1.2+ 引入的机制，替代旧版 dev-dependencies，支持任意命名的依赖分组	默认主依赖属于隐式 main 组；开发依赖通常放在 dev 组
`[tool.poetry.group.dev.dependencies]`	`pyproject.toml` 中定义开发依赖的标准写法	示例：`[tool.poetry.group.dev.dependencies]` 下定义 `pytest = "^7.0"`、`black = "^23.0"`
安装指定组	`poetry install --only [组名]` 或 `poetry install --with [组名]`	`--only main`：仅安装主依赖；`--with dev`：安装主依赖 + dev 组；默认 `poetry install` 安装 main + default 组（通常包含 dev）
默认安装组	可通过 `poetry config` 设置哪些组默认安装	默认行为：main 总是安装，dev 在本地开发时默认安装，CI 中可通过 `--without dev` 排除
多组管理	支持 test、docs、lint 等多个组	示例：`poetry add --group lint flake8`；`poetry install --with lint,test`
与 extras 区别	groups 用于开发阶段依赖管理；extras 用于用户安装时的可选功能	extras 会影响最终分发包的安装选项，groups 不影响分发

💡 最佳实践：将测试、格式化、类型检查等工具放入 dev 组；生产环境部署时使用 poetry install --only main 避免安装无关工具。

第四章：虚拟环境管理

4.1 Poetry 自动创建与使用虚拟环境

方法/机制名称	说明	注意事项
自动创建虚拟环境	Poetry 在首次执行 `poetry install` 或 `poetry run` 时，若检测到项目无关联虚拟环境，会自动创建一个	虚拟环境默认存储在 Poetry 的全局缓存目录中（如 `~/Library/Caches/pypoetry/virtualenvs/` on macOS）
环境命名规则	虚拟环境目录名格式为：`{项目名}-{hash}-{python版本}`，例如 `myproject-AbC123-py3.10`	哈希值基于项目路径生成，确保不同路径下的同名项目不冲突
自动激活机制	所有 `poetry run`、`poetry shell`、`poetry install` 等命令自动在关联的虚拟环境中执行，无需手动激活	用户无需运行 `source venv/bin/activate`，Poetry 内部处理环境隔离
禁用自动创建	可通过配置 `virtualenvs.create false` 禁用自动创建（不推荐）	`poetry config virtualenvs.create false`；此时需用户自行提供虚拟环境

4.2 手动指定 Python 版本或虚拟环境路径

方法名称	语法	用途	代码示例	注意事项
`poetry env use`	`poetry env use [python路径或版本]`	为当前项目指定特定 Python 解释器	`poetry env use python3.10`；`poetry env use /usr/bin/python3.9`；`poetry env use C:\Python311\python.exe`	Poetry 会基于该解释器创建新的虚拟环境；若已存在兼容环境则复用
指定 Python 版本（在 `pyproject.toml` 中）	在 `[tool.poetry.dependencies]` 中声明 `python = "^3.10"`	声明项目支持的 Python 版本范围	`python = ">=3.9,<3.12"`	此约束会影响依赖解析，但不会自动切换解释器；仍需 `poetry env use` 指定具体版本
配置虚拟环境存储路径	`poetry config virtualenvs.path [路径]`	修改所有虚拟环境的默认存储位置	`poetry config virtualenvs.path ./venv` → 将虚拟环境放在项目目录下	设置为相对路径时，路径相对于项目根目录；适用于希望 `.venv` 与项目共存的场景
使用已有虚拟环境	`poetry env use [已有venv的python路径]`	让 Poetry 使用用户已创建的虚拟环境	`poetry env use ./.venv/bin/python`	该虚拟环境必须已安装 Poetry 所需的构建后端（如 poetry-core），否则可能报错

4.3 查看与切换虚拟环境（`poetry env`）

方法名称	语法	用途	代码示例	注意事项
`poetry env info`	`poetry env info [--path]`	显示当前项目关联的虚拟环境信息	`poetry env info`；`poetry env info --path` → 仅输出路径	若项目无关联环境，会提示”未找到虚拟环境”
`poetry env list`	`poetry env list [--full-path]`	列出当前项目所有关联的虚拟环境	`poetry env list`；`poetry env list --full-path` → 显示完整路径	同一项目可关联多个 Python 版本的环境（通过多次 `poetry env use` 创建）
`poetry env remove`	`poetry env remove [环境名或python版本]`	删除指定的虚拟环境	`poetry env remove python3.9`；`poetry env remove myproject-AbC123-py3.9`	删除后，下次运行 `poetry install` 会重新创建（若需要）
`poetry env use`（切换）	`poetry env use [版本]`	切换当前激活的虚拟环境	`poetry env use 3.10`	实际是创建或复用对应版本的环境，并将其设为项目默认环境
`poetry shell`	`poetry shell`	启动子 shell 并激活当前项目的虚拟环境	`poetry shell` → 进入新 shell，提示符通常带环境名	退出 shell 即返回原环境；适合交互式调试

⚠️ 注意：Poetry 不支持”同时激活多个环境”，每个项目在同一时间仅关联一个活跃环境（由 poetry.env 文件或内部状态决定）。

第五章：运行与脚本

5.1 运行命令（`poetry run`）

方法名称	语法	用途	代码示例	注意事项
`poetry run`	`poetry run [命令] [参数...]`	在项目关联的虚拟环境中执行任意命令	`poetry run python script.py`；`poetry run pytest tests/`；`poetry run black .`	自动激活正确的虚拟环境，无需手动 `source venv/bin/activate`
`poetry run` + 可执行脚本	`poetry run [脚本名]`	运行已安装到虚拟环境中的可执行脚本（如 pytest、black）	`poetry run mycli --help`（假设 mycli 是通过 `[tool.poetry.scripts]` 定义的入口）	脚本必须已在当前环境中安装（通常通过 `poetry install` 安装项目自身或依赖）
传递参数	直接附加在命令后	将参数透传给目标程序	`poetry run python -m http.server 8080`	支持任意复杂命令和参数组合
与系统命令隔离	—	确保使用的是虚拟环境中的 Python 和包，而非系统全局版本	`poetry run which python` → 指向虚拟环境中的解释器	避免因全局包污染导致行为不一致

5.2 定义与执行脚本（`[tool.poetry.scripts]`）

配置项/方法	语法/结构	用途	代码示例	注意事项
`[tool.poetry.scripts]`	TOML 表，键为命令名，值为”模块:函数”	定义项目级别的命令行入口点，安装后可在终端直接调用	`[tool.poetry.scripts]` 下定义 `myapp = "myapp.cli:main"`、`data-process = "tools.processor:run"`	函数必须可调用（通常是 `def main(): ...`）；安装项目后（`poetry install`），`myapp` 命令即可全局使用
执行自定义脚本	`poetry run [脚本名]` 或直接 `[脚本名]`（若已安装）	运行通过 scripts 定义的命令	`poetry run myapp --config dev.yaml` 或（在激活环境后）直接：`myapp --config dev.yaml`	必须先运行 `poetry install` 才能使用脚本命令（因为需要写入 entry_points）
脚本函数签名	无参数或支持 `sys.argv` 解析	脚本函数应处理命令行参数	见代码示例：`def main():` 中 `import sys` 并打印 `sys.argv[1:]`	Poetry 不处理参数解析，由脚本自行实现（可集成 argparse、click 等）
多命令分发	同一模块导出多个函数	支持一个包提供多个 CLI 工具	`[tool.poetry.scripts]` 下定义 `serve = "myapp.server:start"`、`migrate = "myapp.db:migrate"`	每个命令独立，便于功能拆分

# myapp/cli.py
def main():
    import sys
    print("Args:", sys.argv[1:])

⚠️ 注意：[tool.poetry.scripts] 生成的是标准 console_scripts entry point，兼容 pip 安装。不要与 shell 脚本混淆（Poetry 不支持直接执行 .sh 文件）。

5.3 在虚拟环境中启动 shell（`poetry shell`）

方法名称	语法	用途	代码示例	注意事项
`poetry shell`	`poetry shell`	启动一个新的子 shell（如 bash、zsh、PowerShell），并自动激活当前项目的虚拟环境	`poetry shell` → 进入新 shell，提示符可能变为：`(myproject-AbC123-py3.10) $`	子 shell 继承父 shell 环境，但 PATH 已指向虚拟环境的 `bin/` 目录
退出 shell	`exit` 或 `Ctrl+D`	退出 Poetry 启动的子 shell，返回原环境	`exit`	不影响其他终端或进程
自动检测 shell	—	Poetry 自动识别系统默认 shell（通过 `$SHELL` 或 Windows 注册表）	无需指定 shell 类型	若需强制指定，可通过设置 `POETRY_SHELL` 环境变量（非官方推荐方式）
与 `poetry run` 对比	—	`poetry shell` 适合长时间交互操作；`poetry run` 适合单次命令	开发调试时常用 `poetry shell`，CI 脚本中常用 `poetry run`	在 `poetry shell` 中可直接运行 `python`、`pytest` 等，无需加 `poetry run` 前缀

💡 提示：在 poetry shell 中，which python 应指向虚拟环境路径，验证环境是否正确激活。

第六章：构建与发布

6.1 构建包（`poetry build`）

方法名称	语法	用途	代码示例	注意事项
`poetry build`	`poetry build`	根据 `pyproject.toml` 构建源码分发包（sdist）和 wheel 包	`poetry build` → 生成 `dist/myproject-0.1.0.tar.gz` 和 `dist/myproject-0.1.0-py3-none-any.whl`	默认同时生成 sdist 和 wheel；输出位于项目根目录下的 `dist/` 文件夹
`poetry build --format`	`poetry build --format [sdist\|wheel]`	仅构建指定格式的包	`poetry build --format wheel`；`poetry build --format sdist`	可多次指定：`--format sdist --format wheel`（等同默认行为）
构建前提	—	项目必须包含有效的 `pyproject.toml`，且包结构可被发现	确保 `packages` 配置正确或使用标准布局（如 `myproject/__init__.py`）	若包未被自动发现，需在 `[tool.poetry]` 中显式声明 `packages = [{include = "mypkg"}]`
构建产物用途	—	生成的 `.whl` 和 `.tar.gz` 可用于本地安装、测试或上传到 PyPI	`pip install dist/myproject-0.1.0-py3-none-any.whl`	wheel 是推荐的分发格式，安装更快；sdist 用于源码归档和兼容性

6.2 发布到 PyPI 或私有仓库（`poetry publish`）

方法名称	语法	用途	代码示例	注意事项
`poetry publish`	`poetry publish`	将 `dist/` 目录中的包上传到配置的仓库（默认 PyPI）	`poetry publish`	首次使用需先配置凭证（见 6.3）；若 `dist/` 为空，会提示”未找到包”
`poetry publish --build`	`poetry publish --build`	先构建再发布（省去手动 `poetry build`）	`poetry publish --build`	推荐在 CI 脚本中使用，确保发布最新构建
`poetry publish --repository`	`poetry publish --repository [仓库名]`	发布到指定的私有仓库	`poetry publish --repository my-pypi`	仓库名需已通过 `poetry source add` 或 `poetry config repositories.my-pypi ...` 配置
`poetry publish --dry-run`	`poetry publish --dry-run`	模拟发布过程，不实际上传	`poetry publish --dry-run`	用于验证配置是否正确，避免误发
发布目标	—	支持 PyPI（pypi）、TestPyPI（test-pypi）及任意兼容 PEP 503 的私有仓库	默认发布到 `https://upload.pypi.org/legacy/`	私有仓库需支持 `POST /legacy/` 接口（如 PyPI、Artifactory、GitLab Package Registry）

⚠️ 注意：重复发布同一版本到 PyPI 会失败（PyPI 不允许覆盖）。如需更新，必须先递增版本号。

6.3 配置仓库凭证（`poetry config`）

方法名称	语法	用途	代码示例	注意事项
`poetry config http-basic.[仓库名]`	`poetry config http-basic.[name] [用户名] [密码]`	为指定仓库配置 HTTP Basic 认证凭证	`poetry config http-basic.pypi __token__ pypi-AgEI...`（使用 PyPI API token）；`poetry config http-basic.my-pypi admin secret`	凭证加密存储在 Poetry 配置目录（如 `~/Library/Application Support/pypoetry/auth.toml`）
配置 PyPI Token（推荐）	—	PyPI 官方推荐使用 API token 而非账号密码	用户名固定为 `__token__`，密码为 `pypi-xxxx` 格式的 token	Token 可在 https://pypi.org/manage/account/token/ 创建
配置私有仓库 URL	`poetry config repositories.[name] [url]`	注册私有仓库地址	`poetry config repositories.my-pypi https://pypi.mycompany.com/simple`	仅配置 URL，不包含认证信息；认证需单独用 `http-basic` 设置
查看配置	`poetry config --list`	列出所有当前配置项	`poetry config --list`	敏感信息（如密码）会显示为 `***`
删除凭证	`poetry config --unset http-basic.[name]`	移除指定仓库的凭证	`poetry config --unset http-basic.pypi`	用于轮换密钥或清理配置
配置作用域	—	支持全局（默认）或项目级配置	`poetry config --local http-basic.pypi ...` → 仅对当前项目生效	项目级配置写入项目根目录的 `poetry.toml`，不应提交到版本控制（含敏感信息）

🔒 安全建议：

永远不要将含凭证的 poetry.toml 提交到 Git。

在 CI 中使用环境变量注入凭证（如 POETRY_PYPI_TOKEN），Poetry 会自动读取。

第七章：高级功能与最佳实践

7.1 多 Python 版本支持

方法/配置项	说明	注意事项
`pyproject.toml` 中声明 Python 兼容范围	在 `[tool.poetry.dependencies]` 中指定 `python = ">=3.8,<3.12"`	此约束用于依赖解析，确保所选依赖在目标 Python 版本下可用；不自动切换解释器
为不同版本创建独立虚拟环境	使用 `poetry env use [版本]` 为每个目标 Python 版本创建环境	示例：`poetry env use 3.8`；`poetry env use 3.10` → 项目可关联多个环境
测试多版本兼容性	结合 tox 或 CI 并行测试多个 Python 版本	虽然 Poetry 本身不提供并行测试，但可配合：`poetry run pytest`（在指定环境中）
构建时指定 Python 标签	Poetry 自动根据当前构建环境的 Python 版本设置 wheel 的兼容标签	若需生成通用 wheel（如纯 Python 包），确保代码无 C 扩展
使用 `--python` 添加条件依赖	为特定 Python 版本添加依赖	示例：`poetry add "dataclasses" --python "<3.7"`

7.2 私有依赖源配置

方法名称	语法	用途	代码示例	注意事项
`poetry source add`	`poetry source add [--priority] [名称] [URL]`	添加私有 PyPI 源	`poetry source add --priority=explicit my-pypi https://pypi.mycompany.com/simple`	`--priority` 可选值：`default`（默认源）、`primary`（优先于 PyPI）、`explicit`（仅当显式指定时使用）
在 `pyproject.toml` 中声明源	手动编辑 `[tool.poetry.source]` 表	使源配置随项目共享	`[tool.poetry.source]` 下配置 `name = "my-pypi"`、`url = "https://pypi.mycompany.com/simple"`、`priority = "primary"`	推荐将源配置写入 `pyproject.toml` 以便团队共享；避免仅用 CLI 配置（不共享）
从私有源安装包	`poetry add --source [名称] [包名]`	显式指定从某私有源安装	`poetry add --source my-pypi internal-utils`	若源设为 `primary` 或 `default`，可省略 `--source`
配置源凭证	见 6.3 节：`poetry config http-basic.[名称] [用户] [密码]`	为私有源提供认证	`poetry config http-basic.my-pypi __token__ abc123`	凭证不写入 `pyproject.toml`，需单独配置（或通过 CI 环境变量注入）
源优先级机制	Poetry 按优先级顺序查询源	优先级顺序：`explicit < primary < default`（PyPI）	若多个源包含同名包，高优先级源胜出；避免将私有源设为 `default`，除非完全替代 PyPI

7.3 Poetry 插件机制

概念/方法	说明	注意事项
Poetry 插件	第三方扩展，通过 hook 机制增强 Poetry 功能（如导出 `requirements.txt`、集成 Docker）	插件需实现 `poetry.plugins.application_plugin` 或 `poetry.plugins.plugin`
安装插件	使用 `poetry self add [插件包]`	`poetry self add poetry-plugin-export`
常见插件示例	`poetry-plugin-export`：导出 `requirements.txt`；`poetry-dynamic-versioning`：动态版本管理；`poetry-conda-plugin`：集成 Conda	插件通常提供新命令，如 `poetry export`
查看已安装插件	`poetry self show plugins`	列出所有已安装插件及其版本
开发自定义插件	需实现 `ApplicationPlugin` 接口并注册 entry point	适用于企业内部工具链集成

⚠️ 注意：插件生态仍在发展中，并非所有功能都有成熟插件。核心功能应优先使用 Poetry 原生命令。

7.4 与 CI/CD 集成（如 GitHub Actions）

操作步骤名称	操作细节	注意事项
安装 Poetry	在 CI 脚本中使用官方安装脚本	`run: curl -sSL https://install.python-poetry.org \| python3 -`
缓存虚拟环境或依赖	使用 `actions/cache` 缓存 `.venv` 或 Poetry 缓存目录	使用 `actions/cache@v4`，`path` 设为 `~/.cache/pypoetry/virtualenvs`，`key` 包含 `${{ runner.os }}-poetry-${{ hashFiles('poetry.lock') }}`
安装依赖	`poetry install --no-interaction --only main`（生产）；`poetry install`（开发）	生产部署应排除 dev 依赖：`poetry install --only main`
运行测试	`poetry run pytest`	确保在正确环境中执行
发布包（带安全凭证）	通过 secrets 注入 PyPI token	`poetry publish --build` 配合环境变量 `POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_API_TOKEN }}`
使用专用 Action（可选）	如 `snok/install-poetry@v1`	配置 `version: 1.8.0`、`virtualenvs-create: true`

✅ 最佳实践：

始终基于 poetry.lock 安装依赖（确保一致性）

在 CI 中验证 poetry.lock 是否与 pyproject.toml 同步（可运行 poetry lock --check）

使用 --no-root 避免在 CI 中安装项目自身（如仅需依赖）：poetry install --no-root

第八章：常见问题与调试

8.1 依赖解析失败处理

问题现象	操作细节（排查与解决步骤）	注意事项
`SolverProblemError` 或 “Because no versions of X match…“	1. 仔细阅读 Poetry 报错信息，定位冲突包；2. 使用 `poetry show --tree` 查看依赖树；3. 检查 `pyproject.toml` 中版本约束是否过于严格（如固定版本）；4. 尝试放宽某个依赖的版本范围（如将 `"==1.5.0"` 改为 `"^1.5"`）；5. 使用 `poetry add --dry-run` 预演添加操作	Poetry 的解析器非常严格，冲突常源于间接依赖的版本不兼容；避免混合使用 `==` 和 `^/~` 约束
解析过程长时间无响应（“Resolving dependencies…” 卡住）	1. 升级 Poetry 到最新版（性能持续优化）；2. 删除 `poetry.lock` 后重试（强制重新解析）；3. 使用 `--verbose` 查看详细进度：`poetry install -vvv`；4. 若使用私有源，检查网络或源可用性	复杂依赖树首次解析可能较慢；Poetry 1.4+ 引入了更快的解析算法
因 Python 版本不兼容导致解析失败	1. 确认 `pyproject.toml` 中 `python = "..."` 范围是否合理；2. 运行 `poetry env use` 指定符合要求的 Python 版本；3. 检查依赖包是否支持当前 Python（如某包仅支持 ≥3.9）	Poetry 会根据声明的 Python 范围过滤依赖版本；本地 Python 版本必须在该范围内
私有包与公共包命名冲突	1. 在 `pyproject.toml` 中为私有源设置 `priority = "primary"`；2. 添加依赖时显式指定源：`poetry add --source my-pypi mylib`	避免私有包与 PyPI 上同名包冲突；建议私有包使用唯一前缀（如 `mycompany-xxx`）

8.2 虚拟环境冲突排查

问题现象	操作细节（排查与解决步骤）	注意事项
`poetry run` 使用了错误的 Python 或包	1. 运行 `poetry env info` 确认当前关联环境路径；2. 检查该环境中是否安装了预期包：`poetry run pip list`；3. 若环境异常，删除并重建：`poetry env remove python`，然后 `poetry install`	可能因手动修改 PATH 或激活其他 venv 导致混淆；Poetry 命令始终使用其管理的环境
提示 “No virtualenv detected” 或 “Virtual environment not found”	1. 确认已运行 `poetry install`；2. 检查项目目录是否存在 `.venv` 或 Poetry 是否在全局缓存中创建了环境；3. 手动指定 Python：`poetry env use python3.10`	若禁用了自动创建（`virtualenvs.create = false`），需自行提供环境
多个项目共享同一虚拟环境（名称哈希冲突）	1. 运行 `poetry env list` 查看所有关联环境；2. 若发现不同项目使用相同环境名，可强制重建：`poetry env remove [环境名]`，然后 `poetry install`	环境名哈希基于项目路径生成；移动项目目录会导致新环境创建，旧环境残留
CI 中虚拟环境路径权限错误	1. 在 CI 脚本中显式设置缓存路径：`poetry config virtualenvs.path .venv`；2. 将 `.venv` 加入缓存而非全局路径	全局缓存路径（如 `/root/.cache`）在某些 CI 容器中可能不可写

8.3 `poetry.lock` 与 `pyproject.toml` 不一致问题

问题现象	操作细节（排查与解决步骤）	注意事项
提示 “Warning: The lock file is not up to date with the latest changes in pyproject.toml”	1. 运行 `poetry lock --check` 验证不一致；2. 若有意图更新依赖，运行 `poetry update`；3. 若仅修改了元数据（如作者、描述），运行 `poetry lock`（不带 `--no-update`）同步 hash	`poetry.lock` 包含 `pyproject.toml` 的内容哈希；任何修改都会触发警告
团队成员安装依赖后行为不一致	1. 确保所有人都提交并拉取了最新的 `poetry.lock`；2. 禁止直接编辑 `poetry.lock`；3. 在 CI 中加入校验步骤：`poetry lock --check`	`poetry.lock` 是确保环境一致的核心文件，必须纳入版本控制
执行 `poetry install` 后未安装最新依赖	1. 检查是否修改了 `pyproject.toml` 但未更新 lock 文件；2. 运行 `poetry update` 或 `poetry install --sync` 强制同步	`poetry install` 默认不升级依赖，仅按 `poetry.lock` 安装；要获取新版本必须先更新 lock
合并分支后 lock 文件冲突	1. 不要手动合并 `poetry.lock`；2. 保留一方的 `pyproject.toml`；3. 删除冲突的 `poetry.lock`；4. 运行 `poetry lock` 重新生成	lock 文件是生成产物，应通过工具重建而非人工合并；确保 `pyproject.toml` 已解决冲突

✅ 预防建议：

在 pre-commit hook 或 CI 中加入 poetry lock --check

团队约定：所有依赖变更必须通过 poetry add/remove/update 操作，禁止直接编辑配置文件

包管理器 Poetry

第一章：Poetry 概述与安装

1.1 Poetry 是什么

1.2 Poetry 与 pip / virtualenv / pipenv 对比

1.3 安装 Poetry

第二章：项目初始化与配置

2.1 创建新项目（poetry new）

2.2 初始化现有项目（poetry init）

2.3 pyproject.toml 配置详解

第三章：依赖管理

3.1 添加依赖（poetry add）

3.2 删除依赖（poetry remove）

3.3 更新依赖（poetry update）

3.4 锁定依赖（poetry.lock 机制）

3.5 依赖组（groups）与开发依赖

第四章：虚拟环境管理

4.1 Poetry 自动创建与使用虚拟环境

4.2 手动指定 Python 版本或虚拟环境路径

4.3 查看与切换虚拟环境（poetry env）

第五章：运行与脚本

5.1 运行命令（poetry run）

5.2 定义与执行脚本（[tool.poetry.scripts]）

5.3 在虚拟环境中启动 shell（poetry shell）

第六章：构建与发布

6.1 构建包（poetry build）

6.2 发布到 PyPI 或私有仓库（poetry publish）

6.3 配置仓库凭证（poetry config）

第七章：高级功能与最佳实践

7.1 多 Python 版本支持

7.2 私有依赖源配置

7.3 Poetry 插件机制

7.4 与 CI/CD 集成（如 GitHub Actions）

第八章：常见问题与调试

8.1 依赖解析失败处理

8.2 虚拟环境冲突排查

8.3 poetry.lock 与 pyproject.toml 不一致问题

2.1 创建新项目（`poetry new`）

2.2 初始化现有项目（`poetry init`）

2.3 `pyproject.toml` 配置详解

3.1 添加依赖（`poetry add`）

3.2 删除依赖（`poetry remove`）

3.3 更新依赖（`poetry update`）

3.4 锁定依赖（`poetry.lock` 机制）

4.3 查看与切换虚拟环境（`poetry env`）

5.1 运行命令（`poetry run`）

5.2 定义与执行脚本（`[tool.poetry.scripts]`）

5.3 在虚拟环境中启动 shell（`poetry shell`）

6.1 构建包（`poetry build`）

6.2 发布到 PyPI 或私有仓库（`poetry publish`）

6.3 配置仓库凭证（`poetry config`）

8.3 `poetry.lock` 与 `pyproject.toml` 不一致问题