写点什么

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

用户头像
Brave
关注
发布于: 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包的能力



发布于: 2020 年 05 月 18 日阅读数: 241
用户头像

Brave

关注

还未添加个人签名 2018.12.13 加入

还未添加个人简介

评论

发布
暂无评论
如何发布一个npm包-创建,发布,更新,撤销及常见问题解决