什么是npm系列:三、如何发布自己的npm包

6,347

读完本篇文章后,你将学到"开发"、“配置”、"发布",最终拥有属于你自己的npm包。

1. 初始化npm

通过npm init命令可以创建初始项目,需要逐步完善一下信息:

package name: (npmtest)
version: (1.0.0)
description:
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)

创建完package.json之后,我们就可以轰轰烈烈的写代码了。

2. 开发Tips

2.1 调试

开发中如何调试是一个痛点,很多人会把代码复制到node_modules中再调试结果,其实我们有更好的办法:"npm link",使用流程如下:

  1. 在包根目录执行npm link
  2. 在项目中执行npm link package-name
  3. 这个时候在项目中实时访问到package-name

目前这种方式在yarn中无法使用。

3. 发布

3.1 创建/登录账号

首先需要在www.npmjs.com/signup注册账号。

完成之后在终端中执行npm login,输入账号密码之后即登录成功。

这里有一点需要注意,如果设置过taobao源,需要修改为npm源,使用如下指令还原:

npm config set registry http://registry.npmjs.org

但是鉴于实际情况,我们在taobaonpm源之间互相切换其实太麻烦了,比较好的解决方案就是配置package.json中的publishConfig字段,配置说明看下一段落。

3.2 package.json 配置

这次主要介绍:

  • publishConfig
  • main
  • files

publishConfig

发布使用的配置。

"publishConfig": {
    "registry": "https://registry.npmjs.org/",
    "tag": "beta",
    "access": "public"
}
  • registry 源地址
  • tag 发布对应的dist-tag标签
  • access 如果是scoped包,一定需要设置为public(付费账号除外)

main

包的入口执行文件,通常我们会指定为index.js

files

我们需要控制npm包的大小,避免安装过程中花费太多时间。一般来说我们只输出编译过的内容、文档、样式等。

package.jsonfiles字段的作用就是控制包含在项目中的内容,它可以设置为文件或者文件名组成的数组。

除此之外,我们还可以在根目录或子目录下创建.npmignore文件,写法和gitignore一致。

有些文件是无法忽略的:

  • package.json
  • README
  • CHANGES / CHANGELOG / HISTORY
  • LICENSE / LICENCE
  • NOTICE
  • The file in the "main" field

以下文件是默认忽略的:

  • .git
  • CVS
  • .svn
  • .hg
  • .lock-wscript
  • .wafpickle-N
  • .*.swp
  • .DS_Store
  • ._*
  • npm-debug.log
  • .npmrc
  • node_modules
  • config.gypi
  • *.orig
  • package-lock.json

3.3 版本管理

版本号遵循语义化版本的规则,由MAJOR.MINOR.PATCH组成,在末尾还可以加上扩展的预发布版本号信息。

  • MAJOR:当你做了不兼容的 API 修改,
  • MINOR:当你做了向下兼容的功能性新增,
  • PATCH:当你做了向下兼容的问题修正。

版本号可以手动修改,也可以通过npm version命令管理:

// 假设当前版本号 v1.0.0

npm version patch
// v1.0.1

npm version prepatch
// v1.0.2-0

npm version minor
// v1.1.0

npm version major
// v2.0.0

npm version的完整命令如下:

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

如果我们要生成1.0.0-alpha.1风格的版本号,可以带上参数--preid:

npm version prerelease --preid=alpha

当我们执行了npm version之后,脚本会自动修改版本号,并在git中创建提交和标签,如果想要禁用该行为,可以传入--no-git-tag-version来阻止。

3.4 tag

npmtag是用于标记不同用途的版本,一个npm包至少会有latest标签,我们可以根据测试版、预览版等不同需求定制标签。

比如我们有一个测试版本要发布,我们可以指定dist tagbeta

npm publish --tag beta

当我们测试完成,准备正式发布的时候,就可以把beta对应版本号演进到latest上。

3.5 发布

当一切准备就绪之后,我们就可以进入发包的冲刺了。

npm publish

注意!可能有人说我为什么看到的只有错误,一般这个时候可以这样排查:

  • registry检查是否正确
  • 包名是否为@somescope/somepackagename形式
  • 版本号是否未更新

如果包属于某个组织下,即@somescope/somepackagename形式的包名,执行命令需要调整为npm publish --access public

经过千辛万苦之后,我们终于发布成功了,可是如果我们发现某个文件漏掉了,再发布一个版本也不太值得,我们就可以使用npm unpublish命令取消24小时之内发布的包,需要注意的是unpublish并不推荐使用。

4. 最佳实践

  • semantic-release 自动生成changelog以及版本管理
  • 代码规范+commit规范 magic-lint
  • cgr 切换npm、yarn源

5. 场景讲解

  • 每次发布操作流程
  • 移除tag

5.1 每次发布流程

  1. 开发功能,并提交代码
  2. npm version major or minor or patch
  3. npm publish

5.2 移除tag

npm dist-tag rm <pkg> <tag>

系列汇总

本文同步发表于作者博客: 什么是npm系列:三、如何发布自己的npm包