语义化版本

npm 生态用 SemVer（MAJOR.MINOR.PATCH）沟通 兼容性预期。发 CLI 或库之前，必须理解 何时升 major——否则下游 nestjs-essentials 项目、npm install 可能无声破坏。

学习目标

• 解读 ^、~ 与精确版本
• 判断改动属于 major / minor / patch
• 为 nva-packages 发布做准备

版本号含义

1.4.2
│ │ └── PATCH：向后兼容 bug 修复
│ └──── MINOR：向后兼容新功能
└────── MAJOR：不兼容的 API 变更

0.y.z 阶段常视为「不稳定」：minor 也可能 breaking——团队内部包要文档写明。

package.json 范围

写法	含义
1.2.3	精确锁定
~1.2.3	允许 patch：>=1.2.3 <1.3.0
^1.2.3	允许 minor：>=1.2.3 <2.0.0
*	不推荐，不可复现构建

与 node-modules 的 package-lock.json 配合：lock 保证 CI 可复现，semver 范围表达 升级策略。

Breaking change 清单

升 MAJOR 当：

• 删除或重命名公共 export
• 改变函数参数含义或默认行为
• CLI flag 删除或语义变更
• Node engines 最低版本提高且旧版不再支持

升 MINOR：新增可选 API、新命令 flag（旧用法仍有效）。

升 PATCH：文档、内部 refactor、bug 修复。

engines 与 peerDependencies

{
  "engines": { "node": ">=20" },
  "peerDependencies": { "typescript": ">=5" }
}

Nest 插件常声明 peerDependencies 对齐 @nestjs/common 版本——见 nest-setup 生成的 package.json。

练习

• 对假想 CLI：「删除 --dry-run 默认 true」应升哪一级？
• 读一个开源包的 CHANGELOG，找一条 MAJOR 说明
• 在 monorepo 场景讨论 lockfile 与 ^ 的冲突（笔记即可）

小结

SemVer 是契约：major 吓退静默升级，patch 才敢自动合并。 下一课创建与发布 npm 包。