---
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 模式。