03-05 · 依赖管理与版本规范

依赖管理是一项被严重低估的工程能力。 90% 的"我电脑上能跑、你电脑不能跑"都来自依赖。这一节给你一套公司硬规范：按需装、按项目锁、按公司清单。

一、三原则

1. 按需装（Just-In-Time）

不要"为了以后用"提前装一堆全局工具
只在某个项目当下需要时才装它的依赖
全局只装"运行时"和"包管理工具"（Python / Node / uv / pnpm / docker），其他统统进项目

2. 按项目锁（Lockfile First）

每个项目必须有 uv.lock / pnpm-lock.yaml
锁文件 必须 commit
CI / 部署只用 lock 文件安装，禁止 pip install xxx / npm install xxx

3. 按公司清单（Catalog Pinning）

公司维护一份 统一版本清单（在 qdy-starters 仓库的 catalog.md）
新项目优先用公司 starter，版本对齐清单
想用清单外的库 → 写 RFC → 通过后再加进清单

二、Python 端：以 uv 为中心

2.1 装 uv（一次性）

bash

curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"  # Windows

2.2 起新项目

bash

mkdir my-svc && cd my-svc
uv init --package
uv python pin 3.11        # 固定 Python 版本

2.3 加依赖

bash

# 主依赖
uv add fastapi sqlalchemy "asyncpg>=0.29"

# dev 依赖
uv add --dev pytest ruff mypy

# 删除
uv remove redis

# 升级
uv lock --upgrade-package fastapi

pyproject.toml 会自动维护，uv.lock 会自动生成 / 更新。

2.4 同步环境（拉别人的代码后第一件事）

bash

uv sync           # 严格按 lock 装，建议 CI 用
uv sync --frozen  # 完全不动 lock，部署用

2.5 跑命令（不需要手动 activate venv）

bash

uv run python script.py
uv run pytest
uv run uvicorn app.main:app --reload

强烈建议：项目里 不要再写 source .venv/bin/activate。直接用 uv run，更不容易出错。

2.6 公司禁用清单（Python）

工具	替代	原因
`pip install -r requirements.txt`	`uv sync`	没有 lock，环境不可重现
`poetry`	`uv`	慢、生态在迁移
`conda`	`uv`	重、与 PyPI 生态分裂
`pip install -g xxx`	`pipx run xxx` 或 `uvx xxx`	全局污染
`requests`	`httpx`	同步 + 老旧
`psycopg2`	`psycopg`（v3，可同步可异步）	psycopg2 维护减弱

三、Node 端：以 pnpm 为中心

3.1 装 Node 与 pnpm

bash

# 用 nvm / fnm 管 Node 版本（不要直接 brew install node）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install --lts
nvm use --lts

npm install -g pnpm

3.2 起新项目

bash

pnpm create vite@latest my-web -- --template react-ts
cd my-web
pnpm install

3.3 加依赖

bash

pnpm add @tanstack/react-query zod
pnpm add -D vitest @testing-library/react

# 升级
pnpm update @tanstack/react-query

# 删除
pnpm remove redux

3.4 同步环境

bash

pnpm install --frozen-lockfile   # CI / 部署

3.5 公司禁用清单（Node）

工具	替代	原因
`npm install` 在团队项目里	`pnpm install`	慢 + 重复装 + 锁文件不稳定
`yarn classic`（v1）	pnpm	已停维护
`axios`	`fetch` + TanStack Query	bundle 大 + 一堆历史包袱
`react-router-dom`（新项目）	TanStack Router	类型差、生态走下坡
`redux` + `redux-saga`	Zustand / TanStack Query	仪式感太重
`moment`	`dayjs` / `date-fns`	bundle 巨大
直接 `npm i -g 5 个东西`	`pnpm dlx` 或 `npx`	全局污染

四、Docker / Docker Compose

4.1 公司开发机推荐配置

工具	推荐
Docker Engine	24+
Docker Compose	v2（`docker compose ...`，不是 `docker-compose`）
镜像加速	阿里云 / DaoCloud（国内）

4.2 公司 Compose 规范

每个项目的 docker-compose.yml 必须包含：

db（PG 16）
redis（如有需要）
不要把后端 API 自己也跑进 compose 里（开发时直接 uv run uvicorn，方便 reload）
部署时再有独立 compose / k8s 配置

详见 02 · 数据库 · PostgreSQL 第二节。

五、操作系统层依赖（不同电脑差最多的地方）

很多 Python / Node 包需要本地编译，依赖系统库。第一天装机就把它们装好：

macOS

bash

xcode-select --install      # 命令行工具

brew install postgresql@16  # 用于 psql 客户端 + libpq
brew install libpq
brew link --force libpq

brew install openssl@3
brew install pkg-config

Ubuntu / Debian

bash

sudo apt update
sudo apt install -y \
    build-essential \
    libssl-dev \
    libffi-dev \
    libpq-dev \
    postgresql-client-16 \
    pkg-config \
    git \
    curl \
    tmux

Windows

推荐 WSL2 Ubuntu，按 Ubuntu 那一套来
原生 Windows 跑 Python / Node 经常踩坑，公司不主推

六、公司"清单 + RFC"流程（重要）

6.1 清单（catalog）

qdy-starters/catalog.md（示意）：

markdown

# 公司技术栈清单（v2026.04）

## Python
- python: 3.11.x
- uv: latest
- fastapi: ">=0.115,<1.0"
- sqlalchemy: ">=2.0.30,<2.1"
- pydantic: ">=2.7,<3.0"
- alembic: ">=1.13"
- httpx: ">=0.27"
- redis: ">=5.0"
- pytest: ">=8.0"

## Node
- node: 22 LTS
- pnpm: 9.x
- vite: ">=6"
- react: ">=19"
- typescript: ">=5.5"
- tailwindcss: ">=4"
- @tanstack/react-query: ">=5"
...

每季度 review 一次，统一升级。

6.2 RFC

如果你想用 清单外 的库，写一份 1 页内的 RFC：

这个库解决什么问题？
替代方案有哪些？为什么不用？
引入它的成本与风险？
谁来维护？

发到 #ai-tools 频道讨论 → 团队 Lead 通过 → 写进清单 → 后续可用。

这样做的目的：避免一年后公司里 5 个项目用了 5 个相互替代的库，谁也接不了别人的代码。

七、常见踩坑速查

现象	原因	解决
`ModuleNotFoundError`，但你确认装了	没用 `uv run`，跑到了系统 Python	用 `uv run python ...`
`pnpm install` 卡住 / 慢	默认 registry 在国外	`pnpm config set registry https://registry.npmmirror.com`
`asyncpg` 装不上（macOS）	缺 libpq / openssl	`brew install libpq openssl@3 && brew link --force libpq`
`psycopg` 装不上（Ubuntu）	缺 libpq-dev	`sudo apt install -y libpq-dev`
Docker 跑 PG 起不来	5432 已被本机 PG 占用	`brew services stop postgresql@16` 或改容器端口
`next: command not found`	没有 activate / 没 install	`pnpm install` 或 `pnpm dlx next ...`
pip 装的包 uv 找不到	两个工具不互通	选定 uv，所有项目用 uv

八、未来股东 · 第一天必做

[ ] 装 uv（macOS/Linux 一行命令）
[ ] 装 Node LTS（用 nvm / fnm，不要 brew install node）
[ ] 装 pnpm（npm i -g pnpm，仅这一条全局）
[ ] 装 Docker / Docker Compose v2
[ ] 看一眼公司 qdy-starters 仓库的 catalog.md
[ ] 把 01-后端-FastAPI 跑起来 + 03-前端-React-Vite 跑起来

完成 = 你的本地工程环境已经达到公司基线。

九、参考资料

返回 → 03 · 开发栈 · README 继续 → 06 · 部署到腾讯云

03-05 · 依赖管理与版本规范 ​

一、三原则 ​

1. 按需装（Just-In-Time） ​

2. 按项目锁（Lockfile First） ​

3. 按公司清单（Catalog Pinning） ​

二、Python 端：以 uv 为中心 ​

2.1 装 uv（一次性） ​

2.2 起新项目 ​

2.3 加依赖 ​

2.4 同步环境（拉别人的代码后第一件事） ​

2.5 跑命令（不需要手动 activate venv） ​

2.6 公司禁用清单（Python） ​

三、Node 端：以 pnpm 为中心 ​

3.1 装 Node 与 pnpm ​

3.2 起新项目 ​

3.3 加依赖 ​

3.4 同步环境 ​

3.5 公司禁用清单（Node） ​

四、Docker / Docker Compose ​

4.1 公司开发机推荐配置 ​

4.2 公司 Compose 规范 ​

五、操作系统层依赖（不同电脑差最多的地方） ​

macOS ​

Ubuntu / Debian ​

Windows ​

六、公司"清单 + RFC"流程（重要） ​

6.1 清单（catalog） ​

6.2 RFC ​

七、常见踩坑速查 ​

八、未来股东 · 第一天必做 ​

九、参考资料 ​

03-05 · 依赖管理与版本规范

一、三原则

1. 按需装（Just-In-Time）

2. 按项目锁（Lockfile First）

3. 按公司清单（Catalog Pinning）

二、Python 端：以 uv 为中心

2.1 装 uv（一次性）

2.2 起新项目

2.3 加依赖

2.4 同步环境（拉别人的代码后第一件事）

2.5 跑命令（不需要手动 activate venv）

2.6 公司禁用清单（Python）

三、Node 端：以 pnpm 为中心

3.1 装 Node 与 pnpm

3.2 起新项目

3.3 加依赖

3.4 同步环境

3.5 公司禁用清单（Node）

四、Docker / Docker Compose

4.1 公司开发机推荐配置

4.2 公司 Compose 规范

五、操作系统层依赖（不同电脑差最多的地方）

macOS

Ubuntu / Debian

Windows

六、公司"清单 + RFC"流程（重要）

6.1 清单（catalog）

6.2 RFC

七、常见踩坑速查

八、未来股东 · 第一天必做

九、参考资料