直接用 poetry 替代 requirements.txt 可行但非无痛切换，需规避构建不一致、ci 失败等问题；关键在权衡切换价值与制定安全迁移策略。
直接用 poetry 替代 requirements.txt 是可行的，但不是“无痛切换”——Flask 项目里若已有成熟 pip-tools 或手写 requirements.in 流程，强行切到 poetry 可能引入构建不一致、CI 失败、Docker 镜像体积突增等问题。关键不在“能不能”，而在“值不值得切”和“怎么切才不翻车”。
poetry init 会覆盖 Flask 项目的隐式依赖假设
poetry init 启动交互式初始化时，默认把 flask 当作“应用主包”而非“库依赖”处理，容易漏掉 gunicorn、python-dotenv 等运行必需项；更隐蔽的问题是它默认启用 virtualenvs.create = true，而很多 Flask 部署场景（如容器内、CI runner）要求复用系统 Python 环境或指定路径。
- 执行前先确认当前目录下没有
pyproject.toml，否则poetry init会尝试合并而非重置 - 手动补全生产依赖：运行
poetry add gunicorn python-dotenv --group production，避免它们混进 dev 组被误删 - 禁用自动虚拟环境：在
pyproject.toml中显式写入virtualenvs.create = false，否则 CI 脚本中poetry install可能卡在找不到venv创建权限
poetry export 生成的 requirements.txt 不等于 pip-compile 的行为
poetry export -f requirements.txt --without-hashes > requirements.txt 输出的文件，缺失 pip-compile 自带的注释（如 # via flask）、无法表达多层间接依赖的版本约束逻辑，且默认不锁定子依赖的 exact 版本（除非加 --with-credentials 和 --format=constraints 组合）。
- CI 中若仍用
pip install -r requirements.txt，可能因未锁定jinja2或werkzeug版本导致运行时异常 - 正确做法是：用
poetry export -f constraints.txt --without-hashes > constraints.txt，再在 Dockerfile 中写pip install --constraint constraints.txt flask gunicorn - 别依赖
poetry export生成可读的 requirements —— 它本质是机器导出格式，不是给人维护的
Flask 的开发/生产环境分离在 poetry 中容易被弱化
传统 requirements.in + pip-compile --extra dev 能清晰分出 dev-requirements.txt，而 poetry 的 [tool.poetry.group.dev.dependencies] 在部署时若忘记加 --without dev，就会把 pytest、black 打进生产镜像。
- 部署命令必须显式带上
--without dev：poetry install --no-dev --no-root -
pyproject.toml中不要把flask放进[tool.poetry.dependencies]的顶层，而应归入[tool.poetry.group.production.dependencies]，否则poetry install默认会装它两次 - 检查是否真没装 dev 包：进入容器后执行
poetry show --tree | grep pytest，有输出就说明没过滤干净
真正麻烦的不是 poetry 本身，而是团队对“依赖即契约”的理解断层——有人改了 pyproject.toml 却不跑 poetry lock，有人 merge 了没更新的 poetry.lock，结果本地能跑、CI 报 ResolverError。这种问题不会因为换工具消失，只会换个形式出现。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
