npm 包发布与版本管理

本节目标

• 理解 package.json 的 name/version/main/exports 与发包流程
• 搞懂语义化版本（SemVer）主.次.补
• 知道 ^ ~ 范围符的区别与「锁文件」的作用

发一个包：写好 package.json，npm publish。

// 包的 package.json（最小可发）
{
  "name": "my-utils",
  "version": "1.2.0",          // 语义化版本：主.次.补
  "type": "module",
  "main": "./dist/index.cjs",  // 老式入口（CJS）
  "exports": { ".": { "import": "./dist/index.mjs", "require": "./dist/index.cjs" } },
  "files": ["dist"]            // 只发 dist，不发源码
}

SemVer：主版本.次版本.补丁

• 主版本：不兼容改动（API 删了/行为变了）
• 次版本：新功能，向后兼容
• 补丁：修 bug，向后兼容

依赖范围：

• ^1.2.0：允许 1.x.x 最新（不含 2.0）→ 拿兼容更新
• ~1.2.0：只允许 1.2.x → 只拿补丁
• lock 文件（package-lock.json）：锁死「实际装的确切版本」，保证团队/CI 一致

名词解释

SemVer（语义化版本）：主.次.补 的版本号约定，用数字告诉你「这次改动有多危险」。升主版本 = 可能不兼容、要改代码；升次版本 = 加了功能但能直接升；升补丁 = 只修 bug。它让「该不该升级依赖」变成看一眼版本号就能判断的事。

锁文件（Lockfile）：package-lock.json / pnpm-lock.yaml 记录「本次安装的每个包的确切版本和依赖树」。它保证「你装的、同事装的、CI 装的」完全一致，避免「我本地好好的、线上挂了」这种「依赖漂移」事故。提交锁文件是工程纪律。

课后练习

练习 1：^1.2.0 和 ~1.2.0 在 npm install 时可能装到的最高版本分别是什么？

答案：^1.2.0 最高到 <2.0.0（即 1.9.9 这种都行，主版本不升）；~1.2.0 最高到 <1.3.0（只补丁，1.2.x）。^ 更松、~ 更紧。CI 通常靠 lock 文件锁死，范围符只在「首次安装/无锁」时起作用。

练习 2：为什么「团队成员都要提交 package-lock.json」？

答案：没有锁文件，每个人 npm install 可能装到「范围内不同的小版本」，出现「我本地能跑你本地报错」的依赖漂移。锁文件把确切版本钉死，全团队/CI 一致，是协作的基本纪律。

总结

发包和版本管理是把「你的模块」变成「别人能信赖的依赖」的最后一公里。我的观点：SemVer 不是形式主义，是对用户的承诺——升主版本前要想清「会不会让人家代码崩」。依赖范围符 ^/~ 我建议「库用 ^ 拥抱兼容更新，关键服务用锁文件钉死」，别裸奔。锁文件必须提交，这是工程底线，没有商量。最后提醒：发之前用 exports 做好门面、用 files 只发构建产物（别把源码/密钥传上去）——专业发包 = 门面清晰 + 版本诚实 + 依赖可复现。