· 全部指南
语义化版本 SemVer
语义化版本通过数字传达兼容性：MAJOR.MINOR.PATCH。不兼容的 API 变更升 MAJOR；向后兼容的新功能升 MINOR；向后兼容的缺陷修复升 PATCH。预发布后缀如 1.0.0-beta.1、2.0.0-rc.2 标记不稳定线，消费者在未 pin 前不应视为生产就绪。
SemVer 是与下游用户的契约，不只是 Git 标签装饰。不升 major 就破坏公开 API 会侵蚀信任，也会让假定 caret 范围安全的 CI 流水线崩溃。semver-calculator 可比较版本、根据变更描述建议下一 bump，并检查 1.2.3 是否满足 ^1.0.0 或 >=2.0.0 <3.0.0 等范围。
发布推荐流程：功能分支开发 → 跑测试 → 决定 bump 级别 → 更新 package.json / Cargo.toml / chart version → 写 changelog → 打 tag v1.4.0 → 发布产物。打 tag 前自问：「现有基于 1.3.x 编译的客户端是否无需改代码即可继续工作？」若否，应升 major。常见错误：每个营销节点重置为 0.1.0；第一次提交就叫 1.0.0；删除 endpoint 却发 1.0.1——实质是 disguised major。
0.y.z 阶段表示「初始开发」，任何事都可能变；仍应在 changelog 记录破坏性变更，让早期采用者能跟上。
依赖范围
包管理器用范围运算符表达可接受版本。npm 中 ^1.2.3 允许不改动规范中最左非零位的更新—— effectively >=1.2.3 <2.0.0；~1.2.3 仅允许 patch：>=1.2.3 <1.3.0。Yarn、pnpm、Cargo、Go modules 语法各异——须读各生态文档。
锁文件（package-lock.json、pnpm-lock.yaml、Cargo.lock）在 CI 与生产中复现精确依赖树。manifest 中的 range 表达意图，lock 表达现实。安全公告迫使 minor 升级前，用 semver-calculator 确认 1.9.0 仍满足 ^1.2.0（应满足），2.0.0 是否不满足（通常不应）。
实例：库 widgets 在 1.8.0 弃用某函数但保留可调用——发 minor 1.9.0。删除该函数须 2.0.0 与迁移说明。^1.0.0 的消费者在无 lockfile 的新装中会收到 1.9.0，但在故意放宽范围前不会收到 2.0.0。
团队约定
合码前写破坏性变更说明：JSON 字段重命名、更严校验、CLI 标志删除。major 发布应附带 codemod 或迁移指南。内部包与公开 npm 模块同等纪律——其它团队也是消费者。
Git tag、Docker 镜像 tag 与包版本应对齐可追溯。镜像 myapi:1.4.2 应对应 Git v1.4.2 与 npm 1.4.2。latest 镜像 tag 只指向稳定 semver，勿指向流动的 main 构建。semver-calculator 可帮 CI 在 push 前校验 tag 一致性。
日历版本（CalVer）适合与发布列车绑定的产品——如 Ubuntu、部分 Terraform provider——但若宣称 SemVer，须遵守其规则。同一仓库混用方案会让自动化困惑。
与 Docker/Git 标签
容器部署常以 tag 而非 digest 引用镜像。浮动 tag 导致意外升级：明天 deploy myapi:1.4 可能拉到层不同的重建镜像。高安全环境应 pin digest，或在 Kubernetes manifest 与 Helm values 中明确 pin semver patch。
Git tag 标记源码快照供审计。git tag v1.2.3 && git push origin v1.2.3 应触发流水线构建并签名 1.2.3 镜像。预发布 tag（v1.3.0-beta.1）进 beta 仓库，而非生产集群。常见错误：用不同产物重打同版本 tag（破坏可复现性）；因「仅内部」跳过 changelog；只改 Docker 镜像却忘了 bump chart version——运维无法关联运行中的软件版本。
审查依赖 PR 时可在 Towalles 本地使用 semver-calculator；粘贴拟议版本串与 package.json 中的范围要求，在合并前捕捉 satisfaction 错误。