乐趣区

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

jiezi

读完本篇文章后，你将学到 ” 开发 ”、“配置”、” 发布 ”，最终拥有属于你自己的 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 创建 / 登录账号

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

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

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

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

但是鉴于实际情况，我们在 taobao 和npm源之间互相切换其实太麻烦了，比较好的解决方案就是配置 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.json的 files 字段的作用就是控制包含在项目中的内容，它可以设置为文件或者文件名组成的数组。

除此之外，我们还可以在根目录或子目录下创建 .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

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

比如我们有一个测试版本要发布，我们可以指定 dist tag 为beta：

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 简介
  • 什么是 npm 系列：二、install 的十八般武艺
  • 什么是 npm 系列：三、如何发布自己的 npm 包
  • to be continued

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

退出移动版