SemVer Cheatsheet - Semantic Versioning Reference
A careless constraint like ^ or ~ silently decides whether your deploy upgrades dependencies or breaks the build. This reference covers MAJOR.MINOR.PATCH structure, prerelease tags, comparison operators, and the npm ranges you actually write (^ ~ >= < * and advanced combos). Use it to write a package.json that upgrades exactly what you want, and to tell why npm picked version X. After reading you read and write version ranges with intent.
Version Number Structure 5
MAJOR.MINOR.PATCH主版本.次版本.修订号
1.2.3example：主版本 1，次版本 2，修订号 3
MAJOR：不兼容的 API 变更破坏性Update时递增
MINOR：向下兼容的功能新增新增功能时递增
PATCH：向下兼容的问题修复修复 bug 时递增
Pre-release & Build Metadata 6
1.0.0-alpha.1内部Test版（alpha）
1.0.0-beta.2公开Test版（beta）
1.0.0-rc.1候选release版（release candidate）
alpha < beta < rc < 正式版先行版本号优先级order
1.0.0-alpha < 1.0.0-alpha.1同标识按数字递增compare
1.0.0+20260721Build元数据（+ 号，不影响优先级）
Version Comparison Operators 5
=1.2.3精确Match指定版本
>1.2.3大于指定版本（不含）
>=1.2.3大于于指定版本
<2.0.0小于指定版本（不含）
<=1.9.9小于于指定版本
npm Version Range Symbols 7
^1.2.3允许 1.x.x，不允许 2.0.0（兼容版本）
~1.2.3允许 1.2.x，不允许 1.3.0（接近版本）
1.2.3 - 2.3.4区间范围（>=1.2.3 且 <=2.3.4）
1.x通配符，equivalent to >=1.0.0 <2.0.0
1.2.x通配符，equivalent to >=1.2.0 <1.3.0
*任意版本（不recommended，易引入破坏性Upgrade）
latest最新稳定版（dist-tag）
npm Advanced Range Syntax 5
1.2.3 || >=2.0.0or运算，Match任一范围
>=1.2.3 <2.0.0空格表示 AND，需同时满足
~1.2 || ^2.0.0复合范围组合使用
github:owner/repo从 Git 仓库Install
file:./local-pkg从本地路径Install
Version Changes & Release Rules 5
feat: 新功能对应 MINOR 递增
fix: 修复 bug对应 PATCH 递增
BREAKING CHANGE: 破坏性变更对应 MAJOR 递增
0.x.x主版本号为 0 表示初始开发，API 不稳定
1.0.0首个正式版，标志着公共 API 稳定
Tips
- ^1.2.3 equals >=1.2.3 <2.0.0 — npm install default behavior.
- ~1.2.3 equals >=1.2.3 <1.3.0 — only patch updates allowed.
- package-lock.json locks exact versions, avoiding uncertainty from ^ and ~.
- Breaking changes must bump the major version, even for tiny changes.
- At major version 0 (0.x.x), any breaking change should bump the minor version.
Official References
Each command links to its official documentation below, so you can verify the latest usage and read deeper.
Maintained by LaoHand
Publicly updated on Jul 21, 2026, continuously proofread against official docs.
Contact Us
Wrong command or description? Send us corrections, business inquiries or product feedback by email.
Contact Us