eafonyang
44 lines
2.3 KiB
Markdown
44 lines
2.3 KiB
Markdown
---
|
||
kind: dependency_management
|
||
name: pnpm 包管理与锁定文件策略
|
||
category: dependency_management
|
||
scope:
|
||
- '**'
|
||
source_files:
|
||
- backend/package.json
|
||
- frontend/package.json
|
||
- backend/pnpm-lock.yaml
|
||
- frontend/pnpm-lock.yaml
|
||
- frontend/pnpm-workspace.yaml
|
||
- backend/Dockerfile
|
||
- frontend/Dockerfile
|
||
---
|
||
|
||
本仓库采用 pnpm 作为统一的 Node.js 依赖管理工具，前后端各自维护独立的 package.json，并通过各自的 pnpm-lock.yaml 锁定依赖版本，确保构建可复现。
|
||
|
||
### 1. 使用的系统与工具
|
||
- 包管理器：pnpm（通过 packageManager 字段强制使用 pnpm@11.5.2）
|
||
- 锁文件：backend/pnpm-lock.yaml、frontend/pnpm-lock.yaml
|
||
- 前端工作区配置：frontend/pnpm-workspace.yaml（仅启用 esbuild 构建支持）
|
||
- Docker 构建：后端与前端 Dockerfile 均 COPY package.json + pnpm-lock.yaml，在镜像内执行安装
|
||
|
||
### 2. 关键文件与位置
|
||
- backend/package.json — Express/Sequelize 等后端依赖声明
|
||
- frontend/package.json — Vue3/Element Plus/Vite 等前端依赖声明
|
||
- backend/pnpm-lock.yaml / frontend/pnpm-lock.yaml — 精确依赖快照
|
||
- frontend/pnpm-workspace.yaml — pnpm workspace 基础配置
|
||
- DEPLOY.md、scripts/upload.sh — 部署脚本中显式包含 lock 文件上传
|
||
|
||
### 3. 架构与约定
|
||
- 双包根结构：backend 与 frontend 各自为独立 npm 项目，无跨包共享依赖；每个目录有自己 node_modules、pnpm-lock.yaml
|
||
- 版本范围：所有依赖使用 ^ 语义化版本前缀，由 pnpm 解析到具体版本并写入 lock 文件
|
||
- 锁定文件纳入版本控制：lock 文件随代码提交，保证 CI/生产环境安装结果一致
|
||
- 忽略 node_modules：前后端 .gitignore 均排除 node_modules/，避免将本地缓存入库
|
||
- 私有源/代理：未发现 .npmrc、.pnpmrc 或 NPM_CONFIG_* 环境变量，默认使用官方 npm registry
|
||
|
||
### 4. 开发者应遵循的规则
|
||
- 始终使用 pnpm 安装依赖：pnpm install（禁止改用 npm/yarn）
|
||
- 新增/升级依赖后必须提交对应的 pnpm-lock.yaml 变更
|
||
- 不要手动编辑 lock 文件，使用 pnpm add/update/remove 命令操作
|
||
- 在容器/Docker 环境中依赖安装阶段不应跳过 lock 文件校验
|
||
- 如需切换 npm 源或添加私有 registry，应在仓库根或对应子项目下提供 .npmrc/.pnpmrc 并纳入版本控制 |