Poetry 是整套依赖生命周期的重定义，核心在于以 poetry.lock 为唯一可信版本来源，必须提交至 Git 并禁止手动编辑；依赖声明用语义化约束（如 ^1.5.0），关键间接依赖需显式锁定；dev/test/optional 依赖须分组声明，多 Python 版本需通过 poetry env use 显式控制。
Poetry 不是 pip 的增强版命令行，而是整套依赖生命周期的重定义。大型项目用它管版本，核心在于放弃“手动冻结”思维，转而信任 poetry.lock 文件 + 语义化约束声明的组合。
poetry.lock 是唯一可信的版本来源，不是可选文件
很多团队把 poetry.lock 加进 .gitignore，或只在 CI 中生成——这是大型项目最常踩的坑。一旦缺失，poetry install 就会按本地 Python 版本、pip 缓存、甚至网络顺序重新解析整个依赖图，结果和队友的环境必然不一致。
- 必须提交
poetry.lock到 Git，且禁止手动编辑 -
poetry install默认行为就是严格校验每个包的哈希值，拒绝安装未被锁文件允许的版本，哪怕pyproject.toml里写的是^2.0 - CI/CD 流程中，应先
poetry install（而非poetry update），确保构建完全复现开发时的依赖状态
用 caret（^）声明主版本兼容性，但锁定关键间接依赖
大型项目里，你声明的包只是冰山一角，真正容易出问题的是传递依赖（transitive dependency）。比如 requests 升级后悄悄改了 urllib3 的接口，而你的代码恰好踩中那个边界 case。
- 直接依赖用
^1.5.0：允许1.x内升级，兼顾安全与更新 - 若发现某次
poetry lock后间接依赖版本跳变并引发问题，立刻用poetry add urllib3==1.26.15 --lock显式固定它 - 不要在
[tool.poetry.dependencies]下堆砌所有间接依赖——只锁那些已知不稳定或有 breaking change 的
dev/test/optional 依赖必须分组声明，不能混进主依赖区
把 pytest 或 black 写进 [tool.poetry.dependencies] 看似省事，实则污染生产镜像、增大攻击面、拖慢 CI 构建速度。
立即学习“Python免费学习笔记（深入）”；
- 开发工具统一放
[tool.poetry.group.dev.dependencies]，测试库放[tool.poetry.group.test.dependencies] - 安装时显式指定：
poetry install --with dev --with test；CI 中可加--no-root跳过安装当前项目本身 - 可选依赖（如数据库驱动）用
[tool.poetry.extras]声明，安装时poetry install --with postgres，避免无用包进入环境
多 Python 版本兼容性必须靠 poetry env use 显式控制
大型项目往往要支持 3.9–3.12 多个版本，仅靠 requires-python = "^3.9" 不够——Poetry 默认选系统里“最匹配”的已安装解释器，但这个“匹配”可能不是你测试过的那个。
- CI 中每轮测试前，先执行
poetry env use 3.11（或绝对路径如poetry env use /opt/python/3.11/bin/python） - 验证当前环境：
poetry run python --version，别信which python，它可能指向 shell 激活的旧环境 - Windows 用户若
poetry env use 3.8报错，检查py -3.8是否可用，或用完整路径C:\Python38\python.exe
大型项目的复杂性不在依赖数量，而在依赖变更的可观测性与可控性。Poetry 的价值不是帮你装得更快，而是让每一次 poetry lock 都变成一次可审计的契约签署——只要 pyproject.toml 和 poetry.lock 同步提交，你就永远知道哪一行改动触发了哪个间接依赖的版本漂移。
