2026-07-16 16:34:18 +08:00
|
|
|
|
---
|
|
|
|
|
|
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
|
2026-07-17 17:17:22 +08:00
|
|
|
|
- frontend/pnpm-workspace.yaml
|
2026-07-16 16:34:18 +08:00
|
|
|
|
- frontend_v2/.npmrc
|
|
|
|
|
|
---
|
|
|
|
|
|
|
2026-07-17 17:17:22 +08:00
|
|
|
|
本仓库采用 pnpm 作为统一的依赖管理工具，通过 packageManager 字段锁定版本，并在后端（backend）与两个前端工程（frontend、frontend_v2）中分别维护各自的依赖声明。核心特征如下：
|
2026-07-16 16:34:18 +08:00
|
|
|
|
|
2026-07-17 17:17:22 +08:00
|
|
|
|
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。
|
2026-07-16 16:34:18 +08:00
|
|
|
|
|
2026-07-17 17:17:22 +08:00
|
|
|
|
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，说明其本身不是工作区根。
|
2026-07-16 16:34:18 +08:00
|
|
|
|
|
2026-07-17 17:17:22 +08:00
|
|
|
|
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 的影响。
|
