PyCharm Workspace Mode + uv Workspace 实战指南

Python 新一代 Monorepo 工程组织方式

---

一、前言

最近打开 PyCharm，你可能会看到这样一个提示：

Enable and try workspace mode Beta

A large project can be split into smaller parts
(like backend, API, and shared code),
making it easier to organize and maintain.

很多人第一反应：

“这是啥？”

“和普通 Project 有什么区别？”

“是不是类似 pnpm workspace？”

“Python 终于开始搞 monorepo 了吗？”

实际上：

这个功能背后，代表的是 Python 工程组织方式的一次重大升级。

而它真正对应的生态，其实是：

uv + pyproject.toml + workspace

这篇文章会从：

• 为什么需要 Workspace
• 什么是 Monorepo
• uv Workspace 怎么用
• PyCharm Workspace Mode 如何配合
• 实际部署怎么做
• 如何避免架构混乱

完整讲清楚。

---

二、传统 Python 项目的问题

很多 Python 项目最开始都长这样：

backend/
├── api/
├── utils/
├── services/
├── rag/
├── crawler/
├── scripts/
└── requirements.txt

刚开始没问题。

但项目越来越大后：

• import 开始混乱
• 共用代码越来越多
• utils 到处复制
• requirements.txt 爆炸
• IDE indexing 越来越慢
• 多服务越来越难管理

最后你会看到：

utils_final.py
utils_v2.py
shared_new/
common_latest/

整个工程开始失控。

---

三、为什么现在都在搞 Monorepo

现代 AI / 后端项目越来越复杂：

例如：

AI 平台
├── API 服务
├── Worker
├── RAG 系统
├── Agent
├── Embedding 服务
├── MCP Server
├── Shared SDK
└── 管理后台

如果每个都是独立仓库：

• 版本同步困难
• 共用代码麻烦
• SDK 更新痛苦
• 调试困难
• 本地开发复杂

于是很多公司开始统一：

一个大仓库（Monorepo）

---

四、什么是 Workspace

Workspace 本质上：

不是部署工具。

而是：

多项目统一开发管理

例如：

my-platform/
├── apps/
│   ├── api/
│   ├── worker/
│   └── crawler/
│
├── libs/
│   ├── shared/
│   ├── rag/
│   └── llm_core/
│
├── pyproject.toml
└── uv.lock

这里：

• apps 是服务
• libs 是共享代码

整个仓库：

一个 workspace

---

五、为什么 PyCharm 要推出 Workspace Mode

以前 PyCharm 的模型：

一个 Project = 一个工程

但现在：

一个仓库可能包含：

• API
• SDK
• Shared
• Worker
• Agent

于是 JetBrains 推出了：

Workspace Mode

它能自动：

• 识别多个子项目
• 建立依赖关系
• 自动配置 SDK
• 自动 linking
• 自动处理 import

---

六、为什么 uv 是关键

现在 Python 新生态核心正在变成：

uv
+
pyproject.toml
+
workspace

而不是：

requirements.txt
setup.py
pip

uv 是 Astral 推出的新一代 Python 包管理工具。

特点：

• 极快
• 原生 workspace
• 自动 venv
• lockfile
• monorepo 支持优秀

---

七、开始实战：创建 Workspace

1. 安装 uv

Mac：

brew install uv

Linux / Mac：

curl -LsSf https://astral.sh/uv/install.sh | sh

检查：

uv --version

---

2. 创建根目录

mkdir my-platform
cd my-platform

初始化：

uv init

---

3. 配置 Workspace Root

修改根目录：

pyproject.toml

[project]
name = "my-platform"
version = "0.1.0"
requires-python = ">=3.12"

[tool.uv.workspace]
members = [
    "apps/*",
    "libs/*"
]

---

八、创建子项目

1. 创建 API 服务

mkdir -p apps/api
cd apps/api

uv init

---

2. 创建共享库

mkdir -p libs/shared
cd libs/shared

uv init --lib

这里：

--lib

表示：

这是一个 library

而不是 app。

---

九、配置 Workspace 内部依赖

例如：

api
依赖
shared

那么：

apps/api/pyproject.toml

[project]
name = "api"
version = "0.1.0"

dependencies = [
    "shared"
]

[tool.uv.sources]
shared = { workspace = true }

这里：

workspace = true

是核心。

意思：

shared 不从 PyPI 安装
而是从当前 workspace 找

---

十、统一安装依赖

回到根目录：

cd my-platform

执行：

uv sync

或者：

uv sync --all-packages

这会：

• 创建统一 .venv
• 安装全部依赖
• 建立 workspace linking
• 生成 uv.lock

---

十一、PyCharm 如何配置 Workspace Mode

直接：

打开整个 my-platform

不是打开：

apps/api

然后：

PyCharm 会自动检测：

workspace project detected

开启：

Enable Workspace Mode

或者：

Settings
→ Project Structure
→ Use pyproject.toml-based project model (Beta)

开启即可。

---

十二、开启后会发生什么

PyCharm 会自动：

自动识别所有成员

例如：

apps/api
libs/shared
libs/rag

自动处理 import

以前：

from shared.utils import xxx

可能飘红。

现在：

自动识别。

自动统一 SDK

整个 workspace 共用：

.venv

不需要手动切换 interpreter。

---

十三、部署怎么办？

很多人会问：

“如果 API 依赖 shared，
那部署 API 时不是整个 monorepo 都要部署？”

答案：

不是

---

十四、要区分两种东西

1. 代码级依赖

例如：

shared/
rag/
llm_core/

这些本来就应该跟随 API。

因为：

API 运行需要它们。

---

2. 服务级依赖

例如：

worker/
crawler/
embedding_service/

这些不应该直接 import。

应该：

• HTTP
• gRPC
• MQ
• Redis Queue

通信。

---

十五、正确的 Monorepo 架构

推荐：

my-platform/
├── apps/
│   ├── api
│   ├── worker
│   ├── crawler
│   └── mcp_server
│
├── libs/
│   ├── shared
│   ├── rag
│   ├── llm_core
│   └── ai_utils

规则：

apps

独立服务。

不要互相 import。

libs

共享代码。

允许 workspace dependency。

---

十六、Docker 如何部署

例如：

API Dockerfile：

FROM python:3.12

WORKDIR /app

COPY . .

RUN uv sync --package api

CMD ["python", "-m", "api"]

这里：

uv sync --package api

只会安装：

• api
• api 的 workspace 依赖

不会安装整个 monorepo。

---

十七、推荐的一套现代 Python 技术栈

当前非常推荐：

uv
+ workspace
+ pyproject.toml
+ ruff
+ pytest
+ PyCharm Workspace Mode

这是目前 Python 新工程体系里，
最接近现代化大型工程的一种方案。

---

十八、总结

PyCharm Workspace Mode 的核心不是：

“多开几个目录”

而是：

Python 开始正式进入 Monorepo 时代

而 uv Workspace：

则是这个生态的真正基础。

未来几年：

uv + workspace

大概率会逐渐成为：

大型 Python 项目的标准组织方式。