一个NPM包/模块是怎么被publish出来的

513 阅读4分钟

什么是包?它与模块有什么区别?

我们引用npm Docs上的一句话:

A package is a file or directory that is described by a `package.json` file.
A package must contain a `package.json` file in order to be published to the npm registry.

包是一个由一个package.json文件描述的文件或者目录,也就是说在一个包里,package.json文件必不可少。

对于模块(module),它不要求一定要有package.json,但是想要publish到npm上,必须得要有package.json文件。

module is any file or directory in the `node_modules` directory that
can be loaded by the Node.js `require()` function.

它只要能通过node.jsrequire()函数进行引用,那么它就是Node.js模块。

scoped包 和 unscoped包

首先,什么是scope

scope 表示范围、作用域。顾名思义,就是为package指定一个作用域,这个作用域可以是个人的,也可以是一个组织的,scope的作用是为了不与其他人或其他组织创建的包出现命名冲突。所以,从另一面讲,unscoped包的包名必须是没有被人用过的、唯一的,不然在publish时会报错。

如何创建一个scoped包和unscoped包?

  1. 创建一个文件夹并切入到该文件夹
mkdir my-package & cd my-package
  1. 创建package.json文件(必不可少)

对于user-scoped包,如下:

npm init --scope=@my-user-name

对于organization-scoped包,则将上面的my-user-name换成组织名称

npm init --scope=@my-org-name

对于unscoped包,则无需向npm init命令传--scope参数

npm init

执行以上命令后会抛出各个询问,我们根据问题逐个给予相应回应就行了。

  1. 按需求往包里添加个人文件和代码

  2. 将包发布到npm registry

对于scopedprivate包(有作用域的私有包)和unscoped包,则直接执行以下命令

npm publish

对于scopedpublic包(有作用域的公共包),则

npm publish --access public

最后提示下面内容,那就是发布成功了。

image.png

这一步有几点要注意的地方:

  • 在publish包之前,需要先在命令行登录你在npm上注册好的账户。首先用npm whoami查看是否处于登录状态,如果不在登录状态,则执行npm login输入账号密码以及一次性密码登录。
  • 发布organization-scoped包之前需要提前在账户中创建好organization,否则会发布失败。
  • 发布unscoped包之前需要看一下自己的包名称是否已经被别人用过,如果发的包名和别人相同,那么将会发布失败。
  • 发布之前到package.json文件检查版本号,每次发布的版本号都不能与之前发布过的相同,不然同样发布失败,具体版本号规范,后面会讲。

private包 和 public包

privatepublic这两个用于表示包的可见性,它们和上面讲的scopedunscoped这两个的关系密不可分。

private包总是有scoped的,并且默认情况下scoped包在发布时不指明--access public,都是属于private的。

unscoped包总是public的,而scoped包要成为public包,必须要在publish时指明--access public

详细可以看一下npm Docs上的 npm package scope, access level, and visibility

package包版本号规范

版本号格式一般为: x.y.z-state,例如1.0.1-beta

  • x表示主版本号major,也就是大版本,一般是做了不兼容旧版本的API修改或更新,例如整个架构的调整,比如vue2升级到vue3。主版本递增时,余下的次版本和修订号都要归零。
  • y表示次版本minor,也就是小版本,一般是做了向下兼容的功能新增。次版本每次递增时,修订号都要重新归零。
  • z表示修订号patch,修订号的更新往往意味着对一些bug的修复。
  • state表示版本状态,属于可选字段,一般可以有以下几个值:
  1. alpha:内部测试版本,bug较多
  2. beta 公测版本,给外部进行测试的版本,也存在着缺陷
  3. rc(release candidate)前面测试版本的进一步版本,实现了全部功能并且解决了绝大部分bug,接近发布,表示正式版本的候选版本

在更新版本号时有几个注意点:

  • 数字型的标识符为非负整数,且不能在前面补零
  • 0.y.z表示开发阶段,一切可能随时改变,非稳定版
  • 1.0.0 界定此版本为初始稳定版,后面的一切更新都基于此版本修改
  • 在发布重要版本时,可以先发布alpha、beta、rc等先行版本状态是以.分隔的标识符,由数字字母组成,alpha、beta、rc后需要带上次数信息,比如1.0.0-alpha.1
  • 某个包版本发行后,后续修改都必须以新版本发行

到这里,对于npm包的介绍就基本结束了,想要看更详细的,可以到npm Docs上查看。