kind, name, category, scope, source_files
| kind |
name |
category |
scope |
source_files |
| dependency_management |
pnpm 多包工作区与镜像源依赖管理 |
dependency_management |
|
| backend/package.json |
| backend/pnpm-lock.yaml |
| frontend/package.json |
| frontend/pnpm-workspace.yaml |
| frontend/.npmrc |
| frontend/packages/axios/package.json |
| frontend/packages/hooks/package.json |
|
系统概览
本项目采用 pnpm 作为统一的 Node.js 包管理器，在前后端两个独立子项目中使用。前端基于 pnpm workspace 构建 monorepo，后端为单包结构；两者均通过 pnpm-lock.yaml 锁定依赖版本，并使用国内 npm 镜像加速安装。
关键文件与位置
- 后端依赖声明:
backend/package.json、backend/pnpm-lock.yaml
- 前端根工作区:
frontend/package.json、frontend/pnpm-workspace.yaml、frontend/pnpm-lock.yaml
- 镜像源配置:
frontend/.npmrc（registry 指向 npmmirror）
- 前端内部子包:
frontend/packages/axios/package.json、frontend/packages/hooks/package.json、frontend/packages/color/package.json、frontend/packages/materials/package.json、frontend/packages/utils/package.json、frontend/packages/scripts/package.json、frontend/packages/uno-preset/package.json
架构与约定
1. 包管理器与版本锁定
- 统一使用 pnpm，后端
package.json 中显式声明 "packageManager": "pnpm@11.5.2"，确保团队与 CI 环境一致。
- 前后端均提交
pnpm-lock.yaml（lockfileVersion 9.0），禁止随意升级依赖，保证可重现构建。
2. 前端 Monorepo 工作区
pnpm-workspace.yaml 将 packages/* 纳入工作区，启用 shamefullyHoist: true、linkWorkspacePackages: true，使子包间以符号链接方式共享依赖，避免重复安装。- 子包之间通过
workspace:* 协议互相引用（如 @sa/axios 依赖 @sa/utils），实现内聚的 UI 工具库复用。
- 子包通过
exports + typesVersions 暴露 TypeScript 入口，对外提供类型安全的 API。
3. 镜像源与私有仓库
frontend/.npmrc 全局设置 registry=https://registry.npmmirror.com/，所有包从国内镜像拉取，提升安装速度。- 未发现
.npmrc 中的 @scope:registry 或 authToken 等私有仓库配置，当前未接入私有 npm 仓库。
4. 引擎与脚本约束
- 前端
engines.node >= 20.19.0、engines.pnpm >= 10.5.0，配合 simple-git-hooks 在 pre-commit 阶段执行 typecheck && lint && fmt，在提交前校验依赖与代码质量。
- 后端仅提供
start / dev（nodemon）脚本，无额外构建步骤。
开发者应遵循的规则
- 统一使用 pnpm：新增依赖一律通过
pnpm add [-D] <pkg> 安装，不要手动编辑 node_modules 或使用 npm/yarn。
- 不直接修改 lock 文件：依赖升级通过
pnpm update 或 pnpm up 触发，由 pnpm 生成新的 pnpm-lock.yaml。
- Monorepo 子包规范：
- 新包放在
frontend/packages/<name>/，并在其 package.json 中声明 exports 和 typesVersions。
- 子包间依赖一律使用
workspace:* 协议，禁止写死版本号。
- 镜像源不可绕过：保持
.npmrc 中的 npmmirror 配置不变；如需引入私有包，应在 .npmrc 中追加对应 scope 的 registry 与 token。
- Node/pnpm 版本对齐：本地 Node 需满足
>=20.19.0，pnpm 需 >=10.5.0，建议使用 nvm 管理以避免版本漂移。
- 后端依赖精简：仅保留运行时必需依赖到
dependencies，开发期工具（如 nodemon）放入 devDependencies，避免污染生产镜像。
eafonyang