如何发布一个 npm 包 - 创建，发布，更新，撤销及常见问题解决

关注
发布于: 2020 年 05 月 18 日
一，前言﻿
这篇文章将介绍如何创建，发布和撤销一个npm包
﻿
通常我们可以将一些常用的或通用的功能封装称为npm包供多个项目进行依赖
如：工具类库，UI 组件库，各类插件等
﻿
在搭建企业开发脚手架时，通常会将公用/核心模块设计为项目依赖，
这就需要制作相关模块的npm包，并上传至企业 npm 私服，
企业内部 npm 私服本身代理了可用的 npm 镜像，如淘宝镜像，
公司项目配置 npm 私服可使用缓存文件，提升工程构建效率
﻿
二，流程介绍（共9个步骤）﻿
这里以向npm官网发布一个npm包为例，进行演示说明（公司内部的私有 npm 包可能会发布到npm私服）
流程如下：
﻿
	1，注册npm账户
	2，验证邮箱（这一步相当重要，也许会遇到意想不到的问题导致发布失败）
	3，npm init初始化工程，并编写代码（package.json介绍，包名命名规则）
	4，登录npm账户（注意切换镜像，用淘宝镜像是不行的；首次和非首次登录）
	5，npm publish发布npm包（包名问题；如何忽略不想上传的部分文件）
	6，查看并测试使用npm包
	7，更新npm包版本（npm的版本管理规则）
	8，撤销已发布的npm包（如何强制撤销）
	9，常见问题及解决方法（镜像问题，登录失败，验证邮箱，包名重复/存在相似等）
﻿
三，1，注册npm账户﻿
想要向npm发布自己的包，需要先注册一个npm账号
﻿
注册地址：https://www.npmjs.com/
﻿
四，2，验证邮箱﻿
在不验证邮箱的情况下，是不能使用npm publish发布npm包的
这里我遇到了一个奇葩的问题，126或qq邮箱在收到验证链接并验证后依然不能发布
最后求助了npm客服问题得到解决，后边会详细记录这部分，
如果正好您此时也遇到了这个问题，希望能有所帮助
﻿
五，3，npm init初始化工程﻿
新建工程目录，初始化npm工程：
﻿
新建工程目录，如：npmModuleDemo，
cd至此目录下执行npm init，初始化一个npm工程
﻿
按照提示配置package.json：
﻿
{
  "name": "demo-publish-npm-module",
  "version": "1.0.0",
  "description": "demo-publish-npm-module",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": ""
  },
  "keywords": [
    "npmmodule",
    "demo"
  ],
  "author": {
    "name": "bravewang",
    "email": "376086383@126.com"
  },
  "license": "MIT"
}
﻿
注意事项：
﻿
name:
	name命名规则-不能包含大写字母，空格及下滑线
	
	由于npm是靠包名（name字段）来确定唯一性的，
	好比android/ios APP在同一个应用市场不能存在相同包名的应用一样，
	所以在填写name时，最好先到npm查一下是否包名已被占用，以避免发布时包名冲突
	冲突了需要修改包名，会在后边问题解决记录方法
	
main：
	配置入口js文件
﻿
简单写一些代码逻辑用于测试-hello：
index.js
﻿
function sayHello(name){
    console.log("hello : " + name);
}
﻿
exports.sayHello = sayHello;
﻿
六，4，登录npm账户﻿
代码写好了还不能发布，需要先登录npm：由于和谐原因，大部分开发者npm配置指向淘宝镜像所以，需要先切换回官方npm镜像，再进行登录：
﻿
查询当前镜像地址：
	npm get registry
设置淘宝镜像：
	npm config set registry http://registry.npm.taobao.org/
设置官方npm镜像:
	npm config set registry https://registry.npmjs.org/
﻿
切换完成后，登录npm：
1)首次登录：npm adduser
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm adduser
Username: bravewang
Password: 
Email: (this IS public) 376086383@qq.com
Logged in as bravewang on https://registry.npmjs.org/.
﻿
2)非首次登录：npm login
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm login
Username: bravewang
Password: 
Email: (this IS public) 376086383@qq.com
Logged in as bravewang on https://registry.npmjs.org/.
﻿
查看当前登录:npm  whoami
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm  whoami
bravewang
﻿
七，5，发布npm包﻿
创建npm工程，编写代码逻辑，切换镜像地址，登录npm后，可以发布了
发布命令：npm publish
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm publish
npm notice 
npm notice ?  demo-publish-npm-module@1.0.0
npm notice === Tarball Contents === 
npm notice 411B   package.json                        
npm notice 82B    index.js               
npm notice 174B   .idea/misc.xml         
npm notice 278B   .idea/modules.xml      
npm notice 458B   .idea/npmModuleDemo.iml
npm notice 186B   .idea/vcs.xml          
npm notice 11.4kB .idea/workspace.xml    
npm notice === Tarball Details === 
npm notice name:          demo-publish-npm-module                 
npm notice version:       1.0.0                                   
npm notice package size:  3.4 kB                                  
npm notice unpacked size: 13.0 kB                                 
npm notice shasum:        15ae6ba456021fc27211d3ab09841e103f26b24b
npm notice integrity:     sha512-0EnajKXHimu1j[...]X/nAb9bzEvDYg==
npm notice total files:   8                                       
npm notice 
+ demo-publish-npm-module@1.0.0
﻿
注意：
为了演示重新发布，刚刚将已发布好的包撤销了，撤销后24小时内不能重新发布，勿玩火
﻿
发布时可能会遇到一些问题导致发布失败，如：
﻿
1）登录授权问题
2）包名被占用或存在相似包名的npm包
3）验证未邮箱
4) 撤销后24小时内不能重新发布
﻿
以上问题见下面的常见问题及解决方法
﻿
如何忽略不想上传的部分文件：
﻿
写入.gitignore 或.npmignore中，上传时就会被自动忽略掉
﻿
八，6，查看并测试npm包﻿
发布成功后，登录npm并搜索刚发布的npm包，可以看到记录：
﻿
下载并测试发布的npm包：
﻿
npm install demo-publish-npm-module
﻿
引入：
﻿
let a = require('demo-publish-npm-module')
a.sayHello('bravewang')
﻿
输出：
﻿
hello ：bravewang
﻿
九，7，更新npm包版本﻿
如果对npm包的内容进行了更新，需要升级npm包版本
﻿
npm社区版本号规则采用semver（语义化版本）
﻿
格式：主版本号.次版本号.修订号
﻿
版本号递增规则：
	主版本号：当你做了不兼容的 API 修改
	次版本号：当你做了向下兼容的功能性新增
	修订号：当你做了向下兼容的问题修正
	
先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸
﻿
查看当前包版本号-npm version：
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm version
{ 'demo-publish-npm-module': '1.0.0',
  npm: '6.4.1',
  ares: '1.10.1-DEV',
  cldr: '32.0',
  http_parser: '2.8.0',
  icu: '60.1',
  modules: '57',
  napi: '3',
  nghttp2: '1.32.0',
  node: '8.12.0',
  openssl: '1.0.2p',
  tz: '2017c',
  unicode: '10.0',
  uv: '1.19.2',
  v8: '6.2.414.66',
  zlib: '1.2.11' }
﻿
更新版本号并发布：
1）直接更新版本号 ： npm version 新版本号
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ npm version 1.0.1
v1.0.1
﻿
执行后，package.json中version字段被更新 : "version": "1.0.1",
﻿
2）可通过npm version <update_type>自动改变版本
﻿
update_type取值,意义及演示：
﻿
// 1）patch：补丁     v1.0.1->v1.0.2
BravedeMacBook-Pro:npmModuleDemo brave$ npm version patch
v1.0.2
// 2）minor：小改     v1.0.2->v1.1.0
BravedeMacBook-Pro:npmModuleDemo brave$ npm version minor
v1.1.0
// 3）major：大改     v1.1.0->v2.0.0
BravedeMacBook-Pro:npmModuleDemo brave$ npm version major
v2.0.0
﻿
十，8，撤销已发布的npm包﻿
撤销命令: npm unpublish 包名
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ 
	npm unpublish demo-publish-npm-module
	
npm ERR! Refusing to delete entire project.
npm ERR! Run with --force to do this.
npm ERR! npm unpublish [<@scope>/]<pkg>[@<version>]
﻿
强制撤销：
﻿
如上报错，可加--force强制撤销
﻿
BravedeMacBook-Pro:npmModuleDemo brave$ 
	npm unpublish demo-publish-npm-module --force
	
npm WARN using --force I sure hope you know what you are doing.
- demo-publish-npm-module
﻿
撤销成功！
﻿
十一，9，常见问题及解决方法﻿
1）npm镜像源问题：﻿
报错信息：
﻿
no_perms Private mode enable, 
only admin can publish this module: npmmoduledemo
﻿
解决方法：
﻿
切换至npm官方地址：
	npm config set registry https://registry.npmjs.org/
﻿
2）登录问题：﻿
报错信息：
﻿
need auth You need to authorize this machine using `npm adduser`
﻿
解决方法：
﻿
需要一个登录会话，通过npm adduser进行登录即可，具体方法上边有不再赘述
﻿
﻿
还有一个登陆问题：
报错信息：
﻿
npm ERR! code EAUTHUNKNOWN
npm ERR! Unable to authenticate, need: Basic
﻿
解决方法：
﻿
网上有说用户名前加~可登陆成功
加了~后确实能登录了，但经测试并不能发布包，至少我是这样的
﻿
请看常见问题及解决方法-4）邮箱未验证问题
﻿
3）存在包名相似或包名冲突﻿
报错信息：
﻿
// 存在相似
Package name too similar to existing packages; 
try renaming your package to '@~bravewang/npmmoduledemo1' 
and publishing with 'npm publish --access=public' 
instead : npmmoduledemo1
﻿
// 包名冲突
You do not have permission to publish "npmmoduledemo". 
Are you logged in as the correct user? : npmmoduledemo
﻿
解决方法：
﻿
修改包名，使用未被占用的包名
﻿
4）邮箱未验证问题﻿
报错信息：
﻿
you must verify your email before publishing a new package: 
https://www.npmjs.com/email-edit : demo-publish-npm-module
﻿
解决方法：
﻿
解决方法就是去验证邮箱，但是，这个过程缺困扰了我，
因为不管使用126，还是qq邮箱收到并打开激活链接后，都显示并未激活
﻿
最后无奈联系了npm社区的客服：
﻿
﻿
﻿
可以看到npm客服的回复：QQ邮箱已经验证成功，但此时依然publish失败
﻿
随后按照邮件所述，登出了npm，重新进入，继续publish还是失败
﻿
随后重新npm adduser，这次试用的是bravewang，而不是~bravewang
登录成功后，npm publish成功
﻿
如果有相同问题，可以参照这个流程试一下，也许能够解决
﻿
十二，结尾﻿
这样，我们就具备了创建，发布，更新，撤销npm包的能力
﻿