poetry install 不等于 pip install -r requirements.txt，因前者依据 pyproject.toml 和 poetry.lock 精确还原整个依赖图并自动管理虚拟环境，后者仅按文本文件安装指定包；Poetry 完全不读 requirements.txt。
Poetry 是当前最接近“开箱即用”复杂依赖管理的 Python 工具，但它的行为和 pip 有本质差异——不是换条命令就能平滑迁移，必须调整对依赖解析、锁定和环境生命周期的理解。
为什么 poetry install 不等于 pip install -r requirements.txt
两者目标不同：pip install -r 是“把文件里写的包装上”，而 poetry install 是“根据 pyproject.toml 声明 + poetry.lock 精确还原整个依赖图”。它会：
- 自动创建并激活虚拟环境（除非你禁用）
- 解析所有传递依赖，不只是直接声明的包
- 强制校验
poetry.lock中每个包的哈希值，防止篡改或缓存污染 - 拒绝安装未被锁文件允许的版本，哪怕
pyproject.toml的语义化版本范围（如^1.5）理论上兼容
常见错误现象：手动改了 requirements.txt 后运行 poetry install 没反应——因为 Poetry 完全不读这个文件。
如何正确声明分组依赖（dev / test / optional）
在 pyproject.toml 中，不要堆在 [tool.poetry.dependencies] 下写所有包。按用途拆分：
立即学习“Python免费学习笔记（深入）”；
- 生产依赖：写进
[tool.poetry.dependencies]，会被打包进 wheel - 开发依赖：用
[tool.poetry.group.dev.dependencies]，例如black、ipython - 测试依赖：用
[tool.poetry.group.test.dependencies]，例如pytest、pytest-cov - 可选依赖（如数据库驱动）：用
[tool.poetry.extras]，例如postgres = ["psycopg2"]，安装时加--with postgres
安装时需显式指定：poetry install --with dev --with test；否则只装 production 依赖。这和 pip install -r requirements-dev.txt 的“全量覆盖”逻辑完全不同。
poetry lock 和 poetry update 的关键区别
这两个命令都重写 poetry.lock，但触发条件和影响范围截然不同：
-
poetry lock：仅重新解析当前pyproject.toml中已声明的依赖，不升级任何包版本。适合新增依赖后生成初始锁文件，或确保锁文件与声明一致 -
poetry update：主动尝试将所有依赖（包括传递依赖）升级到满足约束的最新版本，并更新锁文件。相当于“全面刷新”，CI 中慎用
容易踩的坑：误用 poetry update 导致 CI 构建失败——某个间接依赖悄悄升了主版本，API 已不兼容。建议日常只用 poetry add package 或 poetry lock，升级操作明确指定包名：poetry update requests。
CI/CD 中必须同步 poetry.lock，且不能跳过校验
在 GitHub Actions 或 GitLab CI 中，常见错误是只 poetry install，却没确认 poetry.lock 是否与 pyproject.toml 一致。应加入检查步骤：
poetry lock --check
该命令退出码非 0 表示锁文件过期（比如有人只改了 pyproject.toml 没跑 poetry lock 就提交）。另外，CI 环境默认不启用虚拟环境隔离，务必加 --no-root 避免 Poetry 尝试创建环境失败：
poetry install --no-root --with dev --with test
最常被忽略的一点：Poetry 默认使用系统 Python 创建虚拟环境，若项目要求特定解释器（如 python3.12），必须提前用 poetry env use python3.12 显式绑定，否则 poetry install 可能静默使用错误版本。
