44 lines
3.2 KiB
Markdown
44 lines
3.2 KiB
Markdown
|
---
|
||
|
|
kind: dependency_management
|
||
|
|
name: pnpm 多包工作区与镜像源依赖管理
|
||
|
|
category: dependency_management
|
||
|
|
scope:
|
||
|
|
- '**'
|
||
|
|
source_files:
|
||
|
|
- backend/package.json
|
||
|
|
- frontend/package.json
|
||
|
|
- frontend/pnpm-workspace.yaml
|
||
|
|
- frontend/.npmrc
|
||
|
|
- backend/pnpm-lock.yaml
|
||
|
|
- frontend/packages/axios/package.json
|
||
|
|
---
|
||
|
|
|
||
|
|
## 系统概览
|
||
|
|
|
||
|
|
本项目采用 pnpm 作为统一的包管理器，通过 Monorepo 工作区（workspace）组织前后端代码，并使用 pnpm-lock.yaml 锁定依赖版本。前端基于 pnpm workspace 将公共能力拆分为多个内部包，后端为独立单包结构。
|
||
|
|
|
||
|
|
## 关键文件与位置
|
||
|
|
|
||
|
|
- backend/package.json — 后端 API 服务依赖声明（Express、Sequelize、MySQL2、AWS S3 SDK、Redis 等）
|
||
|
|
- frontend/package.json — 前端主应用依赖声明（Vue3、NaiveUI、Vite、Pinia 等），并通过 workspace:* 引用内部包
|
||
|
|
- frontend/pnpm-workspace.yaml — 定义工作区包路径 packages/* 及 hoist/link 行为
|
||
|
|
- frontend/.npmrc — 全局 npm 镜像源指向 https://registry.npmmirror.com/
|
||
|
|
- backend/pnpm-lock.yaml / frontend/pnpm-lock.yaml — 精确锁定的依赖树快照
|
||
|
|
- frontend/packages/*/package.json — 内部子包（如 @sa/axios、@sa/hooks、@sa/utils 等）的依赖声明
|
||
|
|
|
||
|
|
## 架构与约定
|
||
|
|
|
||
|
|
1. 统一包管理器：根级及各子目录均使用 pnpm，package.json 中显式声明 packageManager: "pnpm@11.5.2"，确保团队与 CI 环境一致性。
|
||
|
|
2. Monorepo 工作区：前端通过 pnpm-workspace.yaml 将 packages/* 纳入同一工作区，配合 shamefullyHoist: true、linkWorkspacePackages: true 实现依赖提升与工作区包软链接。
|
||
|
|
3. 内部包发布模式：前端将通用能力（axios 封装、颜色工具、hooks、UnoCSS 预设等）抽取为 @sa/* 命名空间包，通过 workspace:* 在应用与子包间共享，避免重复安装。
|
||
|
|
4. 镜像源：.npmrc 将默认 registry 替换为国内 npmmirror，加速依赖下载；未配置私有仓库或 .npmrc scope 映射，所有第三方包均来自公开镜像。
|
||
|
|
5. 版本策略：后端生产依赖普遍使用 ^ 语义化范围（如 express ^4.21、sequelize ^6.37），由 lockfile 固定实际解析版本。前端内部包与核心库多使用精确版本号（如 vue 3.5.34、pinia 3.0.4），减少升级不确定性。
|
||
|
|
6. Node 版本约束：前端 engines.node >= 20.19.0、engines.pnpm >= 10.5.0，后端 lockfile 中部分包要求 Node ≥ 18/20，整体以 Node 20+ 为目标运行环境。
|
||
|
|
|
||
|
|
## 开发者应遵循的规则
|
||
|
|
|
||
|
|
- 新增依赖：在后端 backend/package.json 或前端 frontend/package.json 中添加，不要手动编辑 pnpm-lock.yaml；提交前确保已生成最新 lockfile。
|
||
|
|
- 内部包变更：修改 packages/* 下任意子包后，重新执行 pnpm install 使工作区软链接生效；如需对外发布，需更新对应包的 version 字段。
|
||
|
|
- 镜像源切换：若需接入私有 npm 仓库，应在 .npmrc 中追加 @scope:registry= 或全局 registry= 配置，并在 CI 环境变量中注入认证 token。
|
||
|
|
- 版本升级：优先使用 pnpm update --latest 或脚本 pnpm sa update-pkg（前端提供）进行批量升级，再审查 diff 并更新 lockfile。
|
||
|
|
- Node/pnpm 版本：本地开发需满足 node >= 20.19.0、pnpm >= 10.5.0，建议使用 nvm/corepack 自动匹配。
|