工作区和多项目仓库
大型项目可以拆分为较小的部分(如后端、API 和共享代码)，使其更易于组织和维护。 PyCharm 支持使用此类多项目 Python 结构，包括 uv 工作区 和基于路径的依赖（uv、Poetry 和 Hatch）。
启用工作区模式后，包含 pyproject.toml 的目录将成为托管的 Python 项目。 PyCharm 会自动检测工作区成员和子项目，配置环境并管理它们之间的依赖。
启用工作区模式
当打开包含 pyproject.toml 文件的项目时，PyCharm 可能会显示名为 检测到 pyproject.toml 工作区 的通知，建议启用工作区模式。
可以点击 启用 来开启工作区模式，或点击 不再显示 关闭通知。
如果启用工作区模式，PyCharm 会从 pyproject.toml 文件中推导工作区结构和依赖关系。
在设置中启用工作区模式
在 设置 对话框（Ctrl+Alt+S ），转到 。
选择 使用基于 pyproject.toml 的项目模型[测试版] 复选框。
工作空间结构
项目检测
包含 pyproject.toml 的目录将成为托管的 Python 项目。 PyCharm 会读取工作区配置并自动检测所有项目。
项目命名
每个项目名称根据其 [project] name 字段在 pyproject.toml 文件中派生。 如果缺少该字段，则使用目录名。
IDE 中的项目名称必须唯一。 当多个 pyproject.toml 文件解析为相同名称时，IDE 会附加 @N 后缀（从 @1 开始）以区分它们。 为避免此情况，请确保工作区内每个 pyproject.toml 声明唯一的 [project] name。
依赖项
项目间的依赖将从 pyproject.toml 声明中自动解析。 依赖关系会以只读方式在 中可视化展示。 如需更改，请手动编辑 pyproject.toml 文件。
项目结构存储在 .iml 文件的 .idea 目录下，并在每次同步时根据 pyproject.toml 生成。
设置工作区
根据所使用的工具，工作区可以如下组织：
uv 工作区
uv 工作区 使用所有项目共享的单个虚拟环境。 在根 pyproject.toml 中定义工作区成员，并将其作为工作区依赖进行引用：
Poetry 和 Hatch 多项目仓库
在 Poetry 和 Hatch 多项目仓库中，每个项目独立配置并拥有自己的环境。
PyCharm 会自动检测目录结构中的子项目，并为每个项目配置环境。
自动环境配置
当在工作区成员或子项目中打开 .py 或 pyproject.toml 文件后，PyCharm 会检查系统上是否已经存在该项目的环境：
如果存在环境，会自动将其设置为 SDK。
如果不存在环境，会出现文件级通知，建议为该项目创建新环境并安装依赖。
建议的工具由在 pyproject.toml 中指定的构建工具决定，如果有的话。 如果未指定工具，PyCharm 会建议使用 uv （如果已安装）或 venv。
环境一致性
PyCharm 会验证环境一致性，并在 pyproject.toml 中定义的依赖缺失时发出警告。 将提供快速修复以安装缺失的依赖。
如代码中导入了某个包，但未在工作区成员的 pyproject.toml 中列出，快速修复将建议将该包添加到环境并更新对应的 .toml 文件。
同步项目
可以使用 使用 pyproject.toml 同步项目 操作，将项目模型与 pyproject.toml 文件手动同步。 这会基于当前 pyproject.toml 文件状态重建项目模型。
故障排除
PyCharm 力图简化对子项目的环境配置，并让 IDE 自动处理。 但如果没有如预期运行，可以通过跟踪后台执行的命令，并在 Process Output 工具窗口中分析其输出。