2026-07-09 11:16:59 +08:00
|
|
|
---
|
|
|
|
|
kind: dependency_management
|
|
|
|
|
name: 基于 pnpm 与 Docker 的前后端依赖管理
|
|
|
|
|
category: dependency_management
|
|
|
|
|
scope:
|
|
|
|
|
- '**'
|
|
|
|
|
source_files:
|
|
|
|
|
- backend/package.json
|
|
|
|
|
- frontend/package.json
|
|
|
|
|
- backend/pnpm-lock.yaml
|
|
|
|
|
- frontend/pnpm-lock.yaml
|
|
|
|
|
- backend/Dockerfile
|
|
|
|
|
- frontend/Dockerfile
|
|
|
|
|
- frontend/pnpm-workspace.yaml
|
|
|
|
|
---
|
|
|
|
|
|
2026-06-30 14:46:52 +08:00
|
|
|
## 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` 约束，防止意外引入未锁定的新版本。
|
