41 lines
3.4 KiB
Markdown
41 lines
3.4 KiB
Markdown
|
---
|
|||
|
|
kind: dependency_management
|
|||
|
|
name: pnpm 多包工作区与镜像源管理
|
|||
|
|
category: dependency_management
|
|||
|
|
scope:
|
|||
|
|
- '**'
|
|||
|
|
source_files:
|
|||
|
|
- backend/package.json
|
|||
|
|
- frontend/package.json
|
|||
|
|
- frontend_v2/package.json
|
|||
|
|
- frontend_v2/pnpm-workspace.yaml
|
|||
|
|
- frontend_v2/.npmrc
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 1. 使用的系统/工具链
|
|||
|
|
- **包管理器**：统一使用 pnpm（v11），通过 `packageManager` 字段锁定版本，确保团队一致。
|
|||
|
|
- **锁文件策略**：后端 `backend/` 提交 `pnpm-lock.yaml`；前端 `frontend/` 同时存在 `pnpm-lock.yaml` 与 `package-lock.json`（后者为历史遗留）；`frontend_v2/` 仅提交 `pnpm-lock.yaml`。
|
|||
|
|
- **私有仓库/镜像**：`frontend_v2/.npmrc` 配置淘宝镜像 `https://registry.npmmirror.com/`；`frontend/` 未显式配置 `.npmrc`，默认走官方源。
|
|||
|
|
- **无 vendor 目录**：三个子项目均未将 `node_modules` 或第三方源码纳入版本控制，依赖通过安装生成。
|
|||
|
|
|
|||
|
|
## 2. 关键文件与包
|
|||
|
|
- `backend/package.json` — 后端 API 依赖声明（Express、Sequelize、MySQL2、JWT、Axios、Zod、AWS S3 SDK、Winston、ioredis 等）。
|
|||
|
|
- `frontend/package.json` — 旧版前端（Vue 3 + Element Plus + Vite）依赖。
|
|||
|
|
- `frontend_v2/package.json` — 新版前端模板（Soybean Admin，基于 Vue 3 + Naive UI + UnoCSS + TypeScript）。
|
|||
|
|
- `frontend_v2/pnpm-workspace.yaml` — 定义 Monorepo 工作区，包含 `packages/*` 下的内部包（@sa/axios、@sa/color、@sa/hooks、@sa/materials、@sa/utils、@sa/scripts、@sa/uno-preset）。
|
|||
|
|
- `frontend_v2/.npmrc` — 指定 npm 镜像源。
|
|||
|
|
- 各子项目 `.gitignore` 均忽略 `node_modules/`、`dist/`、`.env*` 等。
|
|||
|
|
|
|||
|
|
## 3. 架构与约定
|
|||
|
|
- **Monorepo 结构**：`frontend_v2/` 采用 pnpm workspace，根 `package.json` 作为聚合入口，业务代码在 `src/`，可复用能力下沉到 `packages/` 下以 `workspace:*` 协议引用。
|
|||
|
|
- **版本范围策略**：`backend/` 和 `frontend/` 的依赖普遍使用 `^major.minor` 宽泛范围，便于自动升级；`frontend_v2/` 则对核心依赖使用精确版本号（如 `vue: 3.5.34`、`naive-ui: 2.44.1`），配合 `simple-git-hooks` 的 `update-pkg` 脚本统一管理更新。
|
|||
|
|
- **Node 引擎约束**：`frontend_v2/` 通过 `engines` 强制 Node ≥ 20.19.0、pnpm ≥ 10.5.0，避免环境差异导致的依赖解析问题。
|
|||
|
|
- **构建期依赖隔离**：`frontend_v2/pnpm-workspace.yaml` 中 `allowBuilds` 明确禁止 esbuild、@parcel/watcher 等构建工具在工作区内被提升，减少重复安装。
|
|||
|
|
|
|||
|
|
## 4. 开发者应遵循的规则
|
|||
|
|
1. **统一使用 pnpm**：新增依赖一律通过 `pnpm add [-D] <pkg>` 操作，不要手动编辑 `package.json` 后自行安装。
|
|||
|
|
2. **不提交 node_modules**：所有子项目的 `.gitignore` 已忽略 `node_modules/`，请勿将其纳入版本控制。
|
|||
|
|
3. **镜像源一致性**：新成员应在本地 `.npmrc` 中配置 `registry=https://registry.npmmirror.com/`，与 `frontend_v2/` 保持一致，避免下载缓慢或失败。
|
|||
|
|
4. **Monorepo 内共享包**：如需在 `frontend_v2/packages/` 间共享代码，使用 `workspace:*` 协议并在 `pnpm-workspace.yaml` 的 `packages` 列表中添加路径。
|
|||
|
|
5. **依赖版本策略**：公共库建议固定主版本（`^x.y.z`），框架核心依赖参考 `frontend_v2/` 的精确版本写法以保持稳定性。
|
|||
|
|
6. **更新流程**：优先使用 `pnpm update` 或 `pnpm sa update-pkg`（在 `frontend_v2/` 中）进行批量升级，并检查 `pnpm-lock.yaml` 变更后再提交。
|