eafonyang
41 lines
2.5 KiB
Markdown
41 lines
2.5 KiB
Markdown
---
|
||
kind: dependency_management
|
||
name: pnpm 多包依赖管理（前后端双 package.json）
|
||
category: dependency_management
|
||
scope:
|
||
- '**'
|
||
source_files:
|
||
- backend/package.json
|
||
- backend/pnpm-lock.yaml
|
||
- frontend/package.json
|
||
- frontend/pnpm-workspace.yaml
|
||
- frontend/pnpm-lock.yaml
|
||
- frontend/package-lock.json
|
||
---
|
||
|
||
本仓库采用 pnpm 作为统一的 Node.js 包管理器，前后端各自维护独立的 package.json，通过 lockfile 锁定依赖版本，未启用 monorepo workspace 模式。
|
||
|
||
1. 使用的系统/工具
|
||
- 包管理器：pnpm v11.5.2，在 backend/package.json 与 frontend/package.json 中均通过 packageManager 字段声明，确保团队成员使用一致版本。
|
||
- Lockfile：后端使用 pnpm-lock.yaml（lockfileVersion 9.0），前端同时存在 pnpm-lock.yaml 与 package-lock.json（后者为历史遗留）。
|
||
- 构建工具：前端基于 Vite（vite.config.js），后端无构建步骤，直接运行 src/app.js。
|
||
|
||
2. 关键文件
|
||
- backend/package.json — 后端依赖声明（Express、Sequelize、MySQL2、AWS S3 SDK、Redis、Zod 等）
|
||
- backend/pnpm-lock.yaml — 后端精确锁定的依赖树
|
||
- frontend/package.json — 前端依赖声明（Vue3、Element Plus、Axios、Vite 等）
|
||
- frontend/pnpm-workspace.yaml — 仅开启 allowBuilds.esbuild: true，未定义任何 workspace 包
|
||
- frontend/pnpm-lock.yaml / frontend/package-lock.json — 前端锁文件（二者并存）
|
||
|
||
3. 架构与约定
|
||
- 双包结构：前后端各自独立，不存在共享的 packages/ 或 workspace: 引用；pnpm-workspace.yaml 为空配置，说明当前不是 monorepo。
|
||
- 版本策略：所有依赖均采用 ^ 语义化版本范围（如 express: ^4.21、vue: ^3.3.4），实际安装版本由 lockfile 固定。
|
||
- 私有源/代理：未发现 .npmrc、.pnpmrc 或 registry 相关配置，默认使用 npm 官方源；也未见 @scope 私有包引用。
|
||
- 缓存：根目录存在 .pnpm-store/v11/，表明 pnpm 全局存储已启用。
|
||
|
||
4. 开发者应遵循的规则
|
||
- 统一使用 pnpm 安装/更新依赖，避免混用 npm/yarn，以免生成冲突的 lockfile。
|
||
- 新增依赖时只修改对应子目录的 package.json，提交后让 CI 重新生成 lockfile。
|
||
- 不要手动编辑 lockfile；如需升级，使用 pnpm up <pkg> 或 pnpm update。
|
||
- 清理前端的 package-lock.json，统一以 pnpm-lock.yaml 为准，消除双锁文件带来的歧义。
|
||
- 若未来引入共享包，应在 pnpm-workspace.yaml 中显式声明 workspace，并迁移到 monorepo 模式。 |