Rye init 不自动生成 [tool.rye]，仅当运行 rye sync、add 或修改 Python 版本时才写入；--python 3.12 仅临时指定解释器，不写入配置；rye run 不自动添加当前目录到 PYTHONPATH，需 rye sync 或改用 rye exec。
rye init 之后为什么 pyproject.toml 里没有 [tool.rye]？
Rye 默认不自动生成 [tool.rye] 配置块，它只在你显式运行 rye sync、rye add 或修改 Python 版本时才写入。这和 Poetry 不同——Poetry 初始化就建好 [tool.poetry]，而 Rye 更倾向“按需生成”。
- 如果你希望提前配置 Python 版本或默认 resolver 行为，得手动加
[tool.rye]块，再填python = "3.12"或resolver = "uv" -
rye init --python 3.12也不会自动写进pyproject.toml，它只是临时指定初始化用的解释器 - 缺少该段不会导致命令失败，但后续
rye run或rye list可能用默认 Python（比如系统 Python），而非你预期的版本
用 rye run 执行脚本时找不到模块？
常见现象是：本地开发中 rye run python main.py 报 ModuleNotFoundError，哪怕 main.py 就在项目根目录。
这是因为 rye run 启动的是隔离环境里的 Python 解释器，默认不把当前目录加进 PYTHONPATH，也不自动安装当前包（即使有 pyproject.toml）。
- 要让本地模块可导入，必须先执行
rye sync（等价于安装pip install -e .） - 如果只是临时跑一个脚本且不依赖其他本地包，改用
rye exec python main.py——它会把当前目录加入sys.path - 注意
rye run和rye exec的语义差异：run是“在项目环境中运行命令”，exec是“在项目环境中执行并注入当前路径”
rye build 打出的 wheel 为什么没包含 src/ 下的模块？
Rye 默认采用 PEP 517 构建逻辑，但它的构建后端（build + setuptools）不会自动识别 src/ 布局，除非你在 pyproject.toml 显式声明：
立即学习“Python免费学习笔记（深入）”；
- 在
[build-system]下确保使用requires = ["setuptools>=61.0", "wheel"]，并在[project]中加dynamic = ["version"]（如有需要） - 更关键的是，必须配置
[tool.setuptools]块，例如：[tool.setuptools] py-modules = [] package-dir = {"" = "src"} - 否则
rye build会按传统方式扫描顶层.py文件，跳过src/目录 - 这个坑和
poetry build不同：Poetry 对src/有开箱支持，Rye 完全依赖底层构建后端的配置
CI 中用 rye install 失败，报 Failed to install rye itself
这是 Rye 自举机制在受限环境下的典型故障。Rye 的 rye install 实际上会下载预编译二进制、解压、设 PATH，但它依赖：
可写的
$HOME/.rye（或RYE_HOME指向路径）curl或wget可用，且能访问<a href="https://www.php.cn/link/63037479984401b6b290392b86938bbd">https://www.php.cn/link/63037479984401b6b290392b86938bbd</a>glibc 兼容性（musl 环境如 Alpine 需要额外处理）
CI 中常见做法是跳过
rye install，直接用官方提供的安装脚本：curl -sSf <a href="https://www.php.cn/link/c94230bd397e1a81b4f3e410ff14daf4">https://www.php.cn/link/c94230bd397e1a81b4f3e410ff14daf4</a> | bash若必须用
rye install，请确保RYE_HOME指向可写路径，并在之前mkdir -p $RYE_HOMEmacOS 上如果用 zsh + M1/M2，注意 shell 初始化文件是否加载了
$RYE_HOME/shims——否则rye命令本身都不可见
Rye 的链路不是“一键全通”，每个环节都可能卡在隐式假设上：比如默认用 uv、默认信任 pyproject.toml 结构、默认要求可写家目录。这些不是 bug，但恰恰是容易被跳过的上下文。
