eafonyang
3.4 KiB
3.4 KiB
kind, name, category, scope, source_files
| kind | name | category | scope | source_files | ||||||
|---|---|---|---|---|---|---|---|---|---|---|
| dependency_management | pnpm 多包工作区与镜像源管理 | dependency_management |
|
|
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. 开发者应遵循的规则
- 统一使用 pnpm：新增依赖一律通过
pnpm add [-D] <pkg>操作，不要手动编辑package.json后自行安装。 - 不提交 node_modules：所有子项目的
.gitignore已忽略node_modules/，请勿将其纳入版本控制。 - 镜像源一致性：新成员应在本地
.npmrc中配置registry=https://registry.npmmirror.com/，与frontend_v2/保持一致，避免下载缓慢或失败。 - Monorepo 内共享包：如需在
frontend_v2/packages/间共享代码，使用workspace:*协议并在pnpm-workspace.yaml的packages列表中添加路径。 - 依赖版本策略：公共库建议固定主版本（
^x.y.z），框架核心依赖参考frontend_v2/的精确版本写法以保持稳定性。 - 更新流程：优先使用
pnpm update或pnpm sa update-pkg（在frontend_v2/中）进行批量升级，并检查pnpm-lock.yaml变更后再提交。