---
kind: dependency_management
name: pnpm 多包工作区与镜像源管理
category: dependency_management
scope:
    - '**'
source_files:
    - backend/package.json
    - frontend/package.json
    - frontend_v2/package.json
    - frontend_v2/pnpm-workspace.yaml
    - frontend/pnpm-workspace.yaml
    - frontend_v2/.npmrc
---

本仓库采用 pnpm 作为统一的依赖管理工具，通过 packageManager 字段锁定版本，并在后端（backend）与两个前端工程（frontend、frontend_v2）中分别维护各自的依赖声明。核心特征如下：

1. 包管理器与版本锁定
   - backend/package.json 与 frontend/package.json 均声明 packageManager: pnpm@11.5.2，确保团队使用一致的 pnpm 版本。
   - 各子项目根目录均生成并随代码提交 lockfile（pnpm-lock.yaml），保证安装可复现；frontend 同时存在 package-lock.json，但实际构建脚本由 pnpm 驱动。
   - frontend_v2 额外在 engines 中约束 Node >= 20.19.0、pnpm >= 10.5.0。

2. 私有/共享包与工作区（Workspace）
   - frontend_v2 是真正的 pnpm workspace 工程，pnpm-workspace.yaml 将 packages/* 纳入工作区，并通过 linkWorkspacePackages: true 启用本地包互链。
   - 业务应用通过 workspace:* 协议引用内部包（如 @sa/axios、@sa/hooks、@sa/materials 等），实现跨包复用与统一升级。
   - frontend 也包含 pnpm-workspace.yaml，但仅配置了 allowBuilds.esbuild: true，未定义 packages，说明其本身不是工作区根。

3. 镜像源与网络加速
   - frontend_v2/.npmrc 全局设置 registry=https://registry.npmmirror.com/，所有 npm 包从国内镜像拉取。
   - 未发现 .npmrc 中的私有 registry 或 auth token 配置，表明当前未接入企业私有 npm 源。

4. 依赖分类与更新策略
   - 所有第三方库按运行时依赖（dependencies）与开发依赖（devDependencies）清晰拆分，无 peerDependencies 混用。
   - frontend_v2 提供 update-pkg 脚本（基于 sa update-pkg）辅助批量升级依赖；commit hook 中集成 lint/typecheck/fmt，间接保障依赖变更质量。

5. 容器化与安装隔离
   - 各子项目均有独立 Dockerfile，依赖安装发生在容器内，结合 lockfile 保证构建一致性；node_modules 未被 git 跟踪，符合最佳实践。

开发者约定：
- 新增依赖必须写入对应子项目的 package.json，并重新运行 pnpm install 以更新 lockfile。
- 若需引入新的内部共享包，应在 frontend_v2/packages 下创建并按 workspace:* 引用。
- 修改 .npmrc 或 registry 前需评估对 CI/CD 的影响。