如何发布一个 npm 包

这篇具有很好参考价值的文章主要介绍了如何发布一个 npm 包。希望对大家有所帮助。如果存在错误或未考虑完全的地方,请大家不吝赐教,您也可以点击"举报违法"按钮提交疑问。

前言

npm(node package manager)作为 Node.js 的包管理工具,让世界各地的 JavaScript 开发者方便复用、分享代码以及造轮子;本文将介绍如何发布一个 npm 包,以及使用工具来自动化管理发布 npm 包;本文总览如下:

  1. 准备 npm 账号 & 示例包代码;
  2. 初始化 & 配置 package.json 文件;
  3. 确定发布的包版本;
  4. 发布 npm 包;
  5. 使用 cli 工具 release-it 来自动管理版本、发布包等;
  6. 学习 npm init release-it 原理。

准备

本地需要安装 Node.js 及 npm CLI,npm 将随 Node.js 一起安装,建议使用 Node 版本管理工具来安装 Node,例如 nvm 、n。

注册 npm 账号

第一步先到 npm 注册个账号 www.npmjs.com/signup,跟着注册步骤操作就行。

如何发布一个 npm 包

示例包代码

为了整个流程相对完整,创建个 github 仓库存放代码(本文代码仓库);将仓库克隆到本地后,新建 index.js 文件,这里我们随便搞点工具函数来作为示例。

// index.js  copy from @vue/shared
export const isArray = Array.isArray;
export const isMap = (val) => toTypeString(val) === "[object Map]";
export const isSet = (val) => toTypeString(val) === "[object Set]";
export const isDate = (val) => toTypeString(val) === "[object Date]";
export const isRegExp = (val) => toTypeString(val) === "[object RegExp]";
export const isFunction = (val) => typeof val === "function";
export const isString = (val) => typeof val === "string";
export const isSymbol = (val) => typeof val === "symbol";
export const isObject = (val) => val !== null && typeof val === "object";
export const toTypeString = (val) => Object.prototype.toString.call(val)

复制代码

创建 & 配置 package.json

要发布一个 npm 包,需要创建一个 package.json 文件,用来描述包信息及依赖包。使用 npm init -y 命令创建一个默认的 package.json 文件,默认生成内容如下:

{
  "name": "utils", // 包名,必填且唯一
  "version": "1.0.0", // 版本号,必填,需遵循语义化版本规范
  "description": "", // 包描述信息,利于包检索
  "main": "index.js", // 入口文件,不设置默认为根文件夹下的 index.js
  "scripts": { // 脚本命令
    "test": "echo "Error: no test specified" && exit 1"
  },
  "repository": { // 项目代码仓库
    "type": "git",
    "url": "git+https://github.com/jizai1125/joker1125-utils.git"
  },
  "keywords": [], // 关键字,利于包检索
  "author": "", // 作者信息
  "license": "ISC", // 许可证协议
  "bugs": { // 问题反馈地址
    "url": "https://github.com/jizai1125/joker1125-utils/issues"
  },
  // 项目主页
  "homepage": "https://github.com/jizai1125/joker1125-utils#readme"
}
复制代码

修改为如下,这里只填写了一些字段,根据项目需要配置。

{
  "name": "@joker1125/utils", // 这里为了避免包名冲突,加上命名空间 joker1125
  "version": "1.0.0",
  "description": "js utility functions", 
  "keywords": ["utils", "js-utils"],
  "main": "index.js",
  "author": "joker1125",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/jizai1125/joker1125-utils.git"
  },
  "author": "joker1125",
  "license": "ISC",
  "bugs": {
    "url": "https://github.com/jizai1125/joker1125-utils/issues"
  },
  "homepage": "https://github.com/jizai1125/joker1125-utils#readme"
}
复制代码

要发布一个npm 包,name 和 version 字段是必填的;

包名(name 字段)命名规则:

  • 包名长度不能超过 214 个字符(命名空间也算在里面);
  • 包名所有字符必须小写;
  • 包名可以由连字符 - 组成;
  • 包名不能包含空格,不能以 . 或者 _ 开头,不能包含 ~)('!* 中的任意一个字符;
  • 包名不能包含任何非 url 安全字符(因为包名将作为 url 的一部分);
  • 包名不能与 Node.js / io.js 的核心模块、保留字或黑名单相同,例如 http

可以使用 validate-npm-package-name 包来检查包名是否合法

版本号(version 字段)则需要遵循 semver 规范。

可以使用 node-semver 来检查

扩展阅读:

  • npm Docs - package.json
  • New Package Moniker rules 译文 新的包名规则
  • semver 规范

确定版本号

填写好 package.json 字段后,接下来就是确定我们要发布的版本号,每次对包的更改都应该对应一个版本。

版本号格式

格式:MAJOR.MINOR.PATCH ,值非负整数,且禁止在数字前面补 0

  • MAJOR:主版本号
  • MINOR:次版本号
  • PATCH::修订号

版本号递增逻辑

  • 当有破坏性不兼容的 API 变更时,升级主版本号
  • 当新增一些功能特性时,升级次版本号
  • 当做一些 bug 修复时,升级修订号

当某个版本还不稳定的时候,还可能要先发布一个先行版本,具体可看 semver 规范。

可以使用 npm version 命令来修改版本号

npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease | from-git]
复制代码

栗子 🌰

# 0.0.0 => 0.0.1
npm version patch
# 0.0.0 => 0.1.0
npm version minor
# 0.0.0 => 1.0.0
npm version major
# 0.0.0 => 0.0.1-0
# === 先行版本 ===
npm version prepatch
# 0.0.0 => 0.0.1-alpha.0
npm version prepatch --preid=alpha
# 0.0.1-alpha.0 => 0.0.1-alpha.1
npm version prerelease
复制代码

命令行选项:

  • --preid 指定先行版本的标识符,例如 1.2.3-rc.4 中的 rc
  • -m 或 --message 可以指定 commit 信息,例如 npm version patch -m "Upgrade to %s for reasons” ;
  • -no-git-tag-version 取消创建 git tag 和 commit 信息
  • ...

其他说明:

  • 执行 npm version 命令时,会修改 package.jsonpackage-lock.jsonversion 字段为对应版本;若当前使用 git 来管理文件,还会创建一条 commit 信息和创建一个 tag,可通过指定 -no-git-tag-version 取消生成 commit 和 tag。
  • 执行 npm version 前,git 工作区和暂存区确保没有文件,否则会执行失败。

相关地址:

  • npm CLI - npm version
  • npm semver 版本号在线测试工具

发布 npm 包

npm 登录 & 确定源地址

使用 npm login 命令登录,如下图

如何发布一个 npm 包

因为我们要发布到官方源上面,所以要确保源地址为官方地址 http://registry.npmjs.orghttps://registry.npmjs.com,可以通过 npm config get registry 命令查看当前 registry 源。

如何发布一个 npm 包

如需修改 registry 可通过以下四种方式:

  1. 在全局配置 .npmrc ,可通过命令 npm config set registry= http://registry.npmjs.org/

  2. 在当前项目配置,在当前项目中添加配置文件 .npmrc

    // .npmrc
    registry = http://registry.npmjs.org/
    复制代码
  3. 发布包时指定 --registry 选项,npm publish —registry=http://registry.npmjs.org/

  4. 在当前项目的 package.json 中通过 publishConfig 字段指定。

    // package.json
    {
      ”publicConfig“: {
        "registry": "http://registry.npmjs.org/"
      } 
    }
    复制代码

发布版本

通过命令 npm publish 发布包

npm publish --access public
复制代码

本文示例使用的命名空间为 joker1125 ,在发布时需要指定声明为公有包,因为发布带有命名空间的包 npm 会默认为是要发布私有包,发布私有包需要另外付费的哦!

这里我们通过命令行选项 --access public 声明为公有包,也可通过 package.json 中的 publicConfig 字段配置声明。

如何发布一个 npm 包

以上就是手动发布一个最简单的 npm 包的大致步骤,下面我们借助 cli 工具 release-it 来自动发布。

扩展阅读:

  • npm Docs - Publishing scoped packages

使用 cli 工具 release-it

release-it 工具可以用来升级包版本、生成 changgelog、Git commit \ tag \ push、发布包等。

在项目中运行命令 npm init release-it , 如下:

如何发布一个 npm 包

选择完之后将会自动安装 release-it 包、在 package.json 中加入脚本命令 "release": "release-it”、及生成一个 .release-it.json 初始配置文件。

.release-it 添加以下配置(查看更多配置见 release-it - Configuration),并安装生成 changelog 的插件npm i @release-it/conventional-changelog -D

{
  "github": {
    "release": true
  },
  "git": {
    "commitMessage": "Release: v${version}"
  },
  "plugins": {
    "@release-it/conventional-changelog": {
      "preset": "angular",
      "infile": "CHANGELOG.md"
    }
  }
}
复制代码

因我们发布的包带有命令空间,所以还需要在 package.json 中添加如下配置,声明一下为公有包

{
    "publishConfig": {
        "access": "public"
    }
}
复制代码

然后运行命令 npm run release ,跟着步骤操作选择,之后就会自动生成 changelog、修改包版本、git commit 信息、打 tag、创建 github release、发布包;如下图,至此就完成了 npm 包的自动发布。

如何发布一个 npm 包

npm init release-it 原理

我们前面使用npm init 创建了一个 pakage.json 文件,其实 init 后面还可以接一个参数 <initializer>,该命令格式为:

# npm v6 版本给该命令添加了别名 npm create
npm init <initializer>
复制代码

initializer 是名为 create-<initializer> 的 npm 包 ( 例如 create-react-app , create-vite ),如果缺省该参数的话(也就是只运行 npm init),就会回退到 init 的默认行为,即询问一系列问题,然后创建 package.json 文件,当然我们加上 -y / --yes 参数,就会跳过这些问题。

执行 npm init <initializer> 将会被转换为对应的 npm exec 操作,即会使用 npm exec 来运行 create-<initializer> 包。例子:

# 使用 create-react-app 包创建一个名为 my-react-project 的项目
$ npm init react-app ./my-react-project
# 等同于
$ npm exec create-react-app ./my-react-project
# 等同于
$ npx create-react-app ./my-react-project
复制代码

init 命令在 npm 版本中的区别:

  • v6.x: 会使用 npx 安装该包,并执行该包的 bin。
  • v7+: 使用 npm exec 命令安装该包,并执行该包 bin。

npx 命令介绍:

用于运行 npm 包的命令(本地未安装要运行的包则从远程拉取),例如执行 npx create-vite my-vite-app,如果本地没有安装过 create-vite,则会先从远程拉取安装 create-vite ,然后执行 create-vite my-vite-app

啰嗦这么一大推,回到我们执行的 npm init release-it ,具体发生了什么呢?

  1. 使用 npx / npm exec 执行 create-release-it 包的 bin,本地未安装则先拉取该包;

  2. create-release-it 的 bin 字段指向 index.js 文件,

    如何发布一个 npm 包

    index.js 脚本做的事情:

    • 首先先询问一些问题,然后将配置写入 .release-it.json 文件或 package.json 中;
    • 接着在 package.json 中加入脚本命令 "release": "release-it”
    • 最后执行安装 release-it 包。

总结

通过本文的学习,了解如何发布一个 npm 包,以及利用 release-it 工具自动化管理版本号、发布、生成 changelog、git tag 等;最后学习了 npm init release-it 原理。文章来源地址https://www.toymoban.com/news/detail-465885.html

到了这里,关于如何发布一个 npm 包的文章就介绍完了。如果您还想了解更多内容,请在右上角搜索TOY模板网以前的文章或继续浏览下面的相关文章,希望大家以后多多支持TOY模板网!

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处: 如若内容造成侵权/违法违规/事实不符,请点击违法举报进行投诉反馈,一经查实,立即删除!

领支付宝红包 赞助服务器费用

相关文章

  • 如何发布npm包

    npm(Node Package Manager)是Node.js的包管理器,用于安装、卸载、更新、查看、搜索和发布Node.js包(modules)和软件。npm基于开源的JavaScript运行时Node.js,提供了一个全球最大的开源包管理平台,帮助开发者轻松管理项目的依赖关系。 npm主要功能如下: 安装包:通过npm install命令

    2024年01月19日
    浏览(33)
  • 如何发布插件到npm

    首先  你需要注册一个npm账号   npm 网址:https://www.npmjs.com/    点击 Sign in 跳转到登录页面  点击 Create Account 进行一个新建账户  注册完成后会有一封邮件发送一个一次性密码,到时候验证一下就行。   登录完成之后 点击你的头像 点击Account 进行验证 我这里是验证过了 

    2024年02月12日
    浏览(31)
  • 如何发布自己的npm包

    首先创建一个文件夹(唯一的命名) 创建package.json包,输出npm init,一直回车就好。 创建index.js文件,向外暴露方法。 将包上传或更新到 npm   执行登录命令:npm login 登录npm官网,根据提示输入用户名和密码,邮箱(邮箱必须在注册时进行验证)  发布版本,在登陆命令后接

    2024年02月14日
    浏览(41)
  • npm如何发包、测试以及删除发布包?

    发包: 先在 npm 官网创个号 https://www.npmjs.com/ 2.创好了之后就先创建自己的文件夹,我用的vscode,也可以自己在命令行里面敲,比如我在F:// 前端学习-VUE项目 创建 my_firs_npm 创建之后,你能得到一个包含package.json的东西。 npm推荐最好发包包含这些东西 这里创建README.md和index.

    2024年02月16日
    浏览(37)
  • 前端(vue)npm如何发布自己的包

    4.1然后执行:npm run lib会得到lib文件夹 4.2配置package.json 在npm官网(https://www.npmjs.com/)按照步骤注册一个账号,我这边已经注册好了直接登录就行 6.1注册成功之后然后在终端中输入命令 出现这个之后就说明登陆成功了 6.2更新命令 这就可以使用了!!!

    2024年02月12日
    浏览(52)
  • 自己开发或者修改的组件包如何发布到npm官方市场

    1、注册账号 打开npm官方网站: www.npmjs.com; 进行注册 注册需要用户名,密码和邮箱, 当注册完成后需打开邮箱进行验证(邮箱不验证无法上传) 二、  在需要打包发布的文件夹package.json所在目录下 执行命令:npm init  按照提示修改后一路回车就行; package name 就是安装命令

    2024年02月08日
    浏览(38)
  • 如何编写一个健壮的 npm 包

    比如老王我,用 npm init 新建一个包,改把改把,然后来个 npm publish ,so easy ✌️! Too young too naive, baby 👶! 请容我讲述一些发布过程中踩过的坑。 首先,算了也可以之后有空再说,我们需要通读 npm 的配置文档。 package.json doc 利用 package.json 中 files 字段精简发布体积。 若不指

    2024年02月06日
    浏览(34)
  • 如何自己创建一个工具项目并上传到npm上使用

    选择框架:   选择语言: 在项目中使用命令安装项目依赖:   运行项目:  运行成功界面: 注意: version:当前发布的版本号,项目每次改动后需要修改版本后再发布,  默认要0.0.1开始才能上传,相同版本是传不上去的,一定要记得每次更改了代码都改下版本号。 name: 包

    2024年02月12日
    浏览(42)
  • 如何优雅的发布一个 TypeScript 软件包?

    向 NPM 发布软件包本身并不是一个特别困难的挑战。但是,配置你的 TypeScript 项目以取得成功可能是一个挑战。你的软件包能在大多数项目上运行吗?用户能否使用类型提示和自动完成功能?它能与 ES Modules (ESM) 和 CommonJS (CJS) 风格的导入一起使用吗? 阅读完本篇文章后,你将

    2024年01月23日
    浏览(43)
  • Vue2自己封装的基础组件库或基于Element-ui再次封装的基础组件库,如何发布到npm并使用(支持全局或按需引入使用),超详细

    以下我以 wocwin-admin-vue2 项目为例 修改目录结构,最终如下 1、导入组件,组件必须声明 name 2、定义 install 方法,接收 Vue 作为参数。如果使用 use 注册插件,则所有的组件都将被注册 3、导出的对象必须具有 install,才能被 Vue.use() 方法安装(全局使用) 4、按需引入 5、packa

    2024年02月08日
    浏览(82)

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

博客赞助

微信扫一扫打赏

请作者喝杯咖啡吧~博客赞助

支付宝扫一扫领取红包,优惠每天领

二维码1

领取红包

二维码2

领红包