code-spec/references/json.package.md

基础代码规范 [Json.Package]

• includes package.json package-lock.json yarn.lock pnpm-lock.yaml

下面是 package.json 及 lock 文件的依赖管理规范

依赖变更需经评审 [Json.Package.DependencyChangeReview]

• severity error

• 禁止随意添加、删除、修改依赖
• 新增依赖需在 PR 描述中说明引入理由、使用场景及替代方案评估
• 升级依赖大版本需经团队评审，评估 Breaking Changes 影响
• 删除依赖前确认无其他模块引用

Example: 依赖变更

Good: 有明确理由并评审通过

// PR 描述中说明：
// 引入 lodash-es 用于高性能数组操作，
// 替代方案评估：手写工具函数可维护性差，同意引入
{
  "dependencies": {
    "lodash-es": "^4.17.21"
  }
}

Bad: 随意添加未评审依赖

// 无说明直接提交
{
  "dependencies": {
    "some-random-lib": "^1.0.0"
  }
}

lock 文件禁止手动修改 [Json.Package.NoManualLockEdit]

• severity error

• 禁止直接手动编辑 lock 文件（package-lock.json / yarn.lock / pnpm-lock.yaml）
• lock 文件只能通过包管理器命令（npm/yarn/pnpm install/add/remove/update）自动生成
• PR 中 lock 文件变更需与 package.json 变更对应，禁止出现不一致情况

Example: lock 文件变更

Good: 通过命令自动生成

# 正确方式：使用包管理器命令
pnpm add lodash-es
# 或
pnpm remove unused-lib

Bad: 手动编辑 lock 文件

# 手动修改 pnpm-lock.yaml 中的 checksum 或版本号

依赖版本号使用 caret(^) 或波浪号(~) [Json.Package.DependencyVersion]

• 生产依赖（dependencies）使用 ^ 允许小版本和补丁版本更新
• 开发依赖（devDependencies）可使用 ~ 锁定小版本
• 禁止锁定精确版本（无符号或 =），除非存在特殊兼容性要求

Example: 版本号规范

Good: 使用 ^ 或 ~

{
  "dependencies": {
    "vue": "^3.3.0"
  },
  "devDependencies": {
    "eslint": "~8.50.0"
  }
}

Bad: 锁定精确版本无说明

{
  "dependencies": {
    "vue": "3.3.4"
  }
}