本文介绍开发维护一个npm包常用的基础知识。

npm 注册

前往 www.npmjs.com 注册并登录。如果是使用公司私有npm 则前往对应的网站。

npm 设置镜像源

当需要将包发布到公司内部的 npm 时，需要更改npm镜像源。不然发布的时候将代码发布到外网可能就会被安全的同学找去喝茶。

npm set registry https://bnpm.byted.org
复制代码

但是有时候也需要切换内外部 npm 镜像源，反复以上面的步骤进行更改十分麻烦。因此推荐使用 nrm 来管理(添加、切换) npm 镜像源。

# 安装 nrm
npm install nrm -g

# nrm add <registry> <url>。`registry` 为镜像源别名
nrm add bnpm https://bnpm.byted.org
复制代码

执行 nrm ls 命令查看是否切换至了 bnpm：

  npm -------- https://registry.npmjs.org/
  yarn ------- https://registry.yarnpkg.com/
  cnpm ------- http://r.cnpmjs.org/
  taobao ----- https://registry.npm.taobao.org/
  nj --------- https://registry.nodejitsu.com/
  npmMirror -- https://skimdb.npmjs.com/registry/
  edunpm ----- http://registry.enpmjs.org/
* bnpm ------- https://bnpm.byted.org/
复制代码

如果没有指向 bnpm 则执行 nrm use bnpm 命令进行切换。

包开发

Git 工作流程

为了持续发布（有代码变更就发布），这里使用简化的 Git flow 流程：

检出新分支。

从 master 分支检出新分支，它可以是功能分支（feat/*）、补丁分支（fix/*）。由于这里不需要 develop 分支，所以可以不需要区分补丁分支和热补丁分支（hotfix/*）。

发起 merge request。

新分支开发完成后向 master 分支提交 merge request（后简称 MR，github 上称之为 pull request）。此过程需要设置邀请代码审核的成员（即 Reviewers）。

代码审核，发布预发包。

merge request 发起后，Reviewers 可以对 MR 代码进行审核和评论，审核批准通过后才可进行第4步。此过程中你可以不断的提交代码，但需要 Reviewers 重新审核并批准通过。

因为预发包的发布通常在功能分支发布，所以步骤中可以发布预发包进行测试，详见包发布。

合并 merge request，发布正式包。

预发包测试通过，同时 MR 审批通过后就可以合并 MR，MR 合并至 master 后原来创建的分支会自动删除。并且在合并后的 master 分支发布正式包，详见包发布。

包发布

检查包发布权限

查看自己是否在包的 owner 列表中，如果没有需要找其中的 owner 添加，不给你加就让对方来发布吧…

# 查看指定包的 owner 列表
npm owner ls <pkg>

# 给指定的包添加 owner
npm owner add <user> <pkg>
复制代码

升级版本号

发包前都需要修改版本号（package.json#version 字段）。修改前可以先检查包的已发布版本。

npm view <pkg> versions
复制代码

版本号推荐使用 npm 命令自动修改。假设当前版本为 1.0.1：

# 升级主版本号。version 字段修改为 `2.0.0`。这意味着你做了不兼容的 API 修改
npm version major

# 升级次版本号。version 字段修改为 `1.1.0`。这意味着你做了向下兼容的功能性新增
npm version minor

# 升级修订号。version 字段修改为 `1.0.2`。这意味着你做了向下兼容的 bug 修复
npm version patch

# 升级先行版本号。version 字段修改为 `1.0.1-0`。这意味你准备发布一个预发包供测试使用。
npm version prerelease
复制代码

预发版本可以通过 --preid= 选项再进行细分，可分为内测版本（alpha）、公测版本（beta）和候选版本（rc，即 release candidate），rc 版本相对于 beta 不再加入新的特性，只是用于修复已知 bug，修复后即可成为正式版。

# 发布一个内测版本。1.0.1 => 1.0.1-alpha.0
npm version prerelease --preid=alpha
复制代码

以上是最理想和规范的方式，可根据实际场景进行简化，比如均使用 --preid=alpha 即可。

发布

使用 npm publish 发布包时会默认添加 latest 标记，即 npm publish --tag latest，表示将当前发布的版本标记默认（latest）的最新稳定版本。

--tag 的作用是将包发布到指定的“安装渠道”，用户在安装包时 npm install <pkg>@<tag> 命令则从指定“渠道”中安装最新版本。而我们最常使用的 npm install <pkg> 命令实际是省略了 @latest（稳定“渠道”），完整命令是 npm install <pkg>@latest。

# 发布
npm publish

# 查看发布的版本
npm view <pkg> versions
复制代码

因为上述特性，我们在发布一个预发包（先行版本）则需要注意设置 --tag 选项以避免 tag 被标记为 latest，这样一来用户安装时只有在指定了精确版本或 tag 时才会安装到预发包。npm 中 tag 的指定除 latest（稳定版本）和 next（当前开发中的版本）外都可以自定义，但通常可以有 alpha（测试版本）、experimental（实验性版本）等。

发布时：

# 发布一个测试版本
npm publish --tag alpha
复制代码

安装时：

# 安装精确版本：`npm install <pkg>@<version>`
npm install react@16.9.0-alpha.0

# 指定安装指定 tag 最新版本：`npm install <pkg>@<tag>`。事先可以通过 `npm info <pkg>` 命令查看 `dist-tags` 字段中有哪些 tag
npm install react@alpha
复制代码

预发包

预发包通常只在自己的功能分支或补丁分支发布，注意预发包发布时需要设置 --tag 选项。

npm publish --tag alpha
复制代码

正式包

正式包在 master 分支发布，代码合并至 master 后就意味着马上会进行发布部署，否则在持续发布的过程中，下一次部署可能会在几个小时内发生，你的代码将被一起发布上线，期间其他成员也可能基于 master 创建新分支。

通常将修改版本号和包发布添加到 package.json#scripts 中：

"scripts": {
  // `npm install` 和 `npm publish` 前执行
  "prepare": "npm run build",

  // 发布前打包命令
  "build": "webpack --config webpack.prod.config.js",

  // 升级预发版本号并发布预发包
  "publish:alpha": "npm version prerelease --preid=alpha && npm publish --tag alpha",

  // 升级主版本并发布正式包
  "publish:mmajor": "npm version mmajor && npm publish",

  // 升级次版本并发布正式包
  "publish:minor": "npm version minor && npm publish",

  // 升级修订号并发布正式包
  "publish:patch": "npm version patch && npm publish"
},
复制代码

撤销发布

如果发现已发布的包有 bug，理论上你可以使用 npm unpublish 命令撤销已发布的包，但是通常不建议这么做。通常的做法是先改变 latest 指向进行回退，然后从 master 检出新的补丁分支修复 bug 后发布一个修复版本（升级修订号）。

# 将指定版本标记为稳定的最新版本
npm dist-tag add <pkg>@<version> latest
复制代码

如果包有重大 bug 且被很多人使用，则需要使用 npm deprecate 对所有尝试安装该软件包的人发出弃用警告，此命令可以设置特定版本或某个版本范围内的包需要发出警告信息。

# npm deprecate <pkg>[@<version range>] <message>
npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"
npm deprecate my-thing@1.x "1.x is no longer supported"

# 取消警告将 message 选项设置为 ""
npm deprecate my-thing@"< 0.2.3" ""
复制代码

如果是公司内部 npm 则通常还可以寻找内部维护人员帮助处理。