poetry init 初始化失败主因是项目名含空格、连字符或大写字母，需改为小写字母/数字/下划线且字母开头；可改目录名或用 --no-interaction 跳过交互；import 报错因未使用 Poetry 虚拟环境，应 poetry shell 或 poetry run python；add requests 为宽松版本约束，add requests@^2.31.0 为精确兼容约束。
poetry init 初始化失败：没生成 pyproject.toml 或报错 ValueError: Invalid project name
常见原因是当前目录名含空格、连字符或大写字母，poetry init 对项目名校验严格，只接受小写字母、下划线和数字，且必须以字母开头。
- 先用
pwd确认路径，改掉含空格或-的目录名，比如把my-project改成my_project - 如果只是想快速建个空配置，直接运行
poetry init --no-interaction，跳过交互式提问 - 初始化后检查生成的
pyproject.toml，确认[tool.poetry]下的name字段是合法标识符（如my_project），不是My-Project或123app
poetry install 后 import 报错：ModuleNotFoundError
根本原因不是依赖没装，而是 Python 解释器没指向 Poetry 创建的虚拟环境。Poetry 默认不修改全局 PYTHONPATH 或 PATH，它只管自己的环境。
- 执行
poetry shell进入环境后再运行脚本，这是最稳妥的做法 - 不想进 shell？用
poetry run python myscript.py显式调用环境里的 Python - 编辑器（如 VS Code）需手动选中 Poetry 环境下的 Python 解释器：路径通常是
$(poetry env info --path)/bin/python（macOS/Linux）或$(poetry env info --path)\Scripts\python.exe（Windows） - 别在项目外用系统 Python 直接
python -m pip install，会污染 Poetry 管理逻辑
poetry add requests 和 poetry add requests@^2.31.0 的区别在哪
前者加的是兼容最新版的开放范围（如 requests>=2.31.0,），后者锁死主版本并允许次版本升级，但禁止主版本跃迁。Poetry 默认用 <code>^ 语义，不是 ~。
-
poetry add requests→ 写入requests = "^2.31.0"（等价于>=2.31.0, ） -
poetry add requests@2.31.0→ 写入requests = "2.31.0"（完全锁定） -
poetry add requests@~2.31.0→ 写入requests = "~2.31.0"（等价于>=2.31.0, ） - 生产环境建议用
@锁定具体版本，避免 CI 构建时因新补丁版引入意外行为
多项目共用一个 Poetry cache，但 poetry install 却变慢或出错
Poetry 的全局缓存默认启用，一般没问题；但如果你手动清过 ~/.cache/pypoetry，或在 CI 中未复用缓存层，就会重复下载包甚至解析失败。
立即学习“Python免费学习笔记（深入）”；
- 查缓存位置：
poetry config cache-dir，确认是否被误设为临时路径 - CI 场景下，确保缓存目录（如
~/.cache/pypoetry）被正确挂载或恢复 - 如果某次
poetry install卡在 “Resolving dependencies”，大概率是 PyPI 响应慢或网络策略拦截了https://pypi.org/simple/，可临时配镜像源：poetry config repositories.my-simple https://pypi.tuna.tsinghua.edu.cn/simple/，再poetry config virtualenvs.create false（仅调试用） - 注意：
poetry.lock文件必须提交进 Git，否则不同机器上poetry install可能解析出不同依赖树
