dashboard/.qoder/repowiki/knowledge/zh/基于 pnpm 与 Docker 的前后端依赖管理/dependency_management.md

1. 核心系统与工具

该项目采用 pnpm 作为前后端统一的 JavaScript/TypeScript 包管理器，并通过 Docker Compose 进行容器化编排。项目明确指定了 packageManager 字段（pnpm@11.5.2），利用 Corepack 机制确保开发环境与生产环境使用完全一致的包管理版本。

• 包管理器: pnpm (v11.5.2)
• 锁定文件: pnpm-lock.yaml
• 运行时: Node.js (Backend: v22-alpine, Frontend Builder: v18-alpine)
• 部署编排: Docker Compose

2. 关键文件与配置

• backend/package.json / frontend/package.json: 分别定义了后端 API 和前端 Vue 应用的依赖清单。后端依赖包括 express, sequelize, mysql2, ioredis 等；前端依赖包括 vue, element-plus, axios 等。
• pnpm-lock.yaml: 存在于 backend/ 和 frontend/ 目录下，用于精确锁定依赖树，确保构建的可重复性。
• frontend/pnpm-workspace.yaml: 虽然目前仅包含 allowBuilds 配置，但表明前端目录具备向 pnpm Workspace 演进的潜力或已预留相关配置入口。
• Dockerfile:
  • 后端：通过 corepack enable pnpm 启用 pnpm，并使用 --frozen-lockfile 参数安装生产依赖。
  • 前端：采用多阶段构建，在 builder 阶段安装依赖并打包，最终产物由 nginx:alpine 托管。

3. 架构与约定

• 依赖隔离: 前后端拥有独立的 node_modules 和锁定文件，互不干扰。
• 生产环境优化:
  • 后端 Docker 镜像仅安装 dependencies (--prod)，排除 devDependencies（如 nodemon），减小镜像体积。
  • 前端通过多阶段构建，最终镜像不包含 node_modules 或构建工具，仅保留静态资源。
• 版本一致性: 通过在 package.json 中声明 packageManager 字段，配合 CI/CD 或本地开发时的 Corepack 支持，强制统一工具链版本。

4. 开发者规范

• 安装依赖: 必须使用 pnpm install，禁止使用 npm install 或 yarn，以避免锁定文件冲突。
• 更新依赖: 修改 package.json 后，需重新运行 pnpm install 并同步提交更新后的 pnpm-lock.yaml。
• 容器化构建: 生产环境部署应优先使用 docker-compose up --build，确保依赖安装过程遵循 Dockerfile 中定义的 --frozen-lockfile 约束，防止意外引入未锁定的新版本。