poetry install 失败通常因缺少 poetry.lock 文件；需先运行 poetry lock 或 poetry add 触发生成，且 poetry.lock 必须提交到 Git；poetry init 仅生成 pyproject.toml，不创建环境或锁文件；开发依赖须用 poetry add --group dev 添加；Windows 上 poetry shell 失败多因 PowerShell 执行策略限制。
poetry install 失败时先看 poetry.lock 是否存在
很多第一次用 poetry 的人卡在 poetry install 报错，根本原因是项目里没有 poetry.lock 文件——它不是手动创建的，而是由 poetry lock 生成的。没运行过 poetry lock 或者删了 poetry.lock，poetry install 就会直接失败，报类似 Unable to find lock file 的错误。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 新项目初始化后，先执行
poetry add requests（或任意包），它会自动触发poetry lock - 如果已有
pyproject.toml但没poetry.lock，手动跑一次poetry lock再poetry install - 别把
poetry.lock加进.gitignore——它和package-lock.json一样，必须提交，否则别人拉代码后环境不一致
poetry init 不等于项目就 ready 了
poetry init 只是交互式生成 pyproject.toml 的骨架，它不会创建虚拟环境，也不安装任何依赖，更不会写入 poetry.lock。很多人以为按完回车就完事了，结果 poetry run python main.py 直接报 ModuleNotFoundError。
实操建议：
立即学习“Python免费学习笔记（深入）”；
-
poetry init后必须至少加一个依赖，比如poetry add click，才能真正激活锁文件和虚拟环境 - 检查虚拟环境是否就绪：运行
poetry env info，看到Path字段有实际路径才算成功 - 如果
poetry env info报No environment has been created，说明还没触发环境创建，补一个poetry add或poetry install即可
poetry add --group dev 和 dev-dependencies 的写法差异
开发依赖不能只靠改 pyproject.toml 手动加字段，那样 poetry.lock 不会更新，poetry install 也不会装进去。必须用命令明确指定分组，否则 pytest 这类工具可能只在本地有、CI 环境里缺失。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 添加开发依赖：用
poetry add pytest --group dev（Poetry 1.2+）或旧版的poetry add pytest -G dev - 验证是否生效：查看
pyproject.toml中是否出现[tool.poetry.group.dev.dependencies]区块，且poetry.lock里对应包出现在develop = true的条目下 - 安装时区分场景：
poetry install默认装全部（含 dev），而 CI 中常用poetry install --without dev来跳过测试工具
Windows 上 poetry shell 启动失败常见于 PowerShell 执行策略
在 Windows 上运行 poetry shell 报 execution policy 错误，不是 Poetry 本身的问题，而是 PowerShell 默认禁止运行本地脚本。这不是权限问题，也不是杀毒软件拦截，纯粹是系统策略限制。
实操建议：
立即学习“Python免费学习笔记（深入）”；
- 临时解决：在当前 PowerShell 窗口运行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser - 别用
Administrator权限去改机器级策略，没必要，也容易引发其他工具冲突 - 替代方案：不用
poetry shell，改用poetry run python script.py，完全绕过 shell 激活环节
pyproject.toml 里 [[tool.poetry.source]] 和 requires-python 怎么写，不是命令一跑就自动适配的。 
