从零开始发布一个 npm 包

张夫尧 2017-10-20 17:36:16

一、npm init

首先进入到项目目录,执行 npm init,效果如图:

npm init

一般来说,一路回车即可,如果对应的有 git 仓库,它也会自动填充。几个东西值得一说:

  1. name 项目名,也就是以后发布的时候的 npm 包名。发布前随时可以改,所以也不用太担心重复。
  2. entry point 入口文件,也就是别人 npm install 之后,require 所使用到的文件。
  3. license 开源协议,这里建议使用完全无传染性的 MIT 和有一定传染性的 LGPL-3.0,也可以根据自己的需求选择开源协议。

执行完毕后,目录中会生成一个 package.json 文件,其中 entry point 在这个文件中的字段名是 main,也可以随时改,所以也不用太在意。

package.json 字段详解:http://ju.outofmemory.cn/entry/130809

二、开发与测试

在这个文件夹下进行自己功能的开发,首次开发 npm 包可能准备的不够充分,需要有 demo 来进行测试。假设包名为 hello,此时应该这样测试:

  1. 开发完成后,修改好 name 和 entry point。
  2. 执行 npm link。此时 hello 会作为一个本地的 npm 包被映射到全局的 node_modules。
  3. 在 demo 的代码中引用这个包(require(“hello”)),构建完毕后,打开 demo 查看效果。
  4. 发现问题后,在 hello 中修改代码。
  5. 在 demo 中重新构建,打开 demo 再次查看效果。如此直到开发完成。
  6. 进入 hello 目录,执行 npm unlink。

三、构建包

如果你的包需要构建,应当手动在 package.json 的 script 一栏添加 build 值,并完善 readme.md,然后就可以通过 npm run build 进行构建。如图:

npm script

四、发布包

在命令行执行 npm adduser 注册一个 npm 用户;如果已经是 npm 用户,可以执行 npm login 进入登陆状态。

一切已经准备好了,npm publish 即可。

五、更新包

当修改一个包,再度发布时,一定要更新包的版本号,不建议手动修改,建议使用命令 npm version。

这个命令同时会自动为 git 留下一条版本号的 commit。

npm 不允许发布重复的版本号,即使你 unpublish 过也不行,这点需要注意。

六、长期维护的测试

每次都使用 npm link 的方式无疑是不优雅的。长期维护一个包时,一定要写他的测试脚本,然后集成到 npm run test 命令里。