---
kind: dependency_management
name: pnpm 多包工作区与镜像源依赖管理
category: dependency_management
scope:
    - '**'
source_files:
    - 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）脚本，无额外构建步骤。

## 开发者应遵循的规则

1. **统一使用 pnpm**：新增依赖一律通过 `pnpm add [-D] <pkg>` 安装，不要手动编辑 `node_modules` 或使用 npm/yarn。
2. **不直接修改 lock 文件**：依赖升级通过 `pnpm update` 或 `pnpm up` 触发，由 pnpm 生成新的 `pnpm-lock.yaml`。
3. **Monorepo 子包规范**：
   - 新包放在 `frontend/packages/<name>/`，并在其 `package.json` 中声明 `exports` 和 `typesVersions`。
   - 子包间依赖一律使用 `workspace:*` 协议，禁止写死版本号。
4. **镜像源不可绕过**：保持 `.npmrc` 中的 npmmirror 配置不变；如需引入私有包，应在 `.npmrc` 中追加对应 scope 的 registry 与 token。
5. **Node/pnpm 版本对齐**：本地 Node 需满足 `>=20.19.0`，pnpm 需 `>=10.5.0`，建议使用 nvm 管理以避免版本漂移。
6. **后端依赖精简**：仅保留运行时必需依赖到 `dependencies`，开发期工具（如 nodemon）放入 `devDependencies`，避免污染生产镜像。