导航

在Verdaccio搭建npm私有服务器中，我们介绍了如何搭建一个Npm私有服务器；服务器搭建完成后，我们本章来学习一下如何上传我们自己的npm包。

前端模块化作为前端必备的一个技能，已经在前端开发中不可或缺；而模块化带来项目的规模不断变大，项目的依赖越来越多；随着项目的增多，如果每个模块都通过手动拷贝的方式无异于饮鸩止渴，我们可以把功能相似的模块或组件抽取到一个npm包中；然后上传到私有npm服务器，不断迭代npm包来更新管理所有项目的依赖。

npm包的基本了解

首先我们来了解一下实现一个npm包需要包含哪些内容。

打包

通常，我们把打包好的一些模块文件放在一个目录下，便于统一进行加载；是的，npm包也是需要进行打包的，虽然也能直接写npm包模块的代码（并不推荐），但我们经常会在项目中用到typescript、babel、eslint、代码压缩等等功能，因此我们也需要对npm包进行打包后再进行发布。

在深入对比Webpack、Parcel、Rollup打包工具中，我们总结了，rollup相比于webpack更适合打包一些第三方的类库，因此本文主要通过rollup来进行打包。

npm域级包

随着npm包越来越多，而且包名也只能是唯一的，如果一个名字被别人占了，那你就不能再使用这个名字；假设我想要开发一个utils包，但是张三已经发布了一个utils包，那我的包名就不能叫utils了；此时我们可以加一些连接符或者其他的字符进行区分，但是这样就会让包名不具备可读性。

在npm的包管理系统中，有一种scoped packages机制，用于将一些npm包以@scope/package的命名形式集中在一个命名空间下面，实现域级的包管理。

域级包不仅不用担心会和别人的包名重复，同时也能对功能类似的包进行统一的划分和管理；比如我们用vue脚手架搭建的项目，里面就有@vue/cli-plugin-babel、@vue/cli-plugin-eslint等等域级包。

我们在初始化项目时可以使用命令行来添加scope：

npm init --scope=username

相同域级范围内的包会被安装在相同的文件路径下，比如node_modules/@username/，可以包含任意数量的作用域包；安装域级包也需要指明其作用域范围：

npm install @username/package

在代码中引入时同样也需要作用域范围:

require("@username/package")

加载规则

在npm包中的package.json文件，我们经常会看到main、jsnext:main、module、browser等字段，那么这些字段都代表了什么意思呢？其实这跟npm包的工作环境有关系，我们知道，npm包分为以下几种类型的包：

只能在浏览器端使用的
只能在服务器端使用的
浏览器/服务器端都可使用

假如我们现在开发一个npm包，既要支持浏览器端，也要支持服务器端（比如axios、lodash等），需要在不同的环境下加载npm包的不同入口文件，只通过一个字段已经不能满足需求。

首先我们来看下main字段，它是nodejs默认文件入口, 支持最广泛，主要使用在引用某个依赖包的时候需要此属性的支持；如果不使用main字段的话，我们可能需要这样来引用依赖：

import('some-module/dist/bundle.js')

所以它的作用是来告诉打包工具，npm包的入口文件是哪个，打包时让打包工具引入哪个文件；这里的文件一般是commonjs(cjs)模块化的。

有一些打包工具，例如webpack或rollup，本身就能直接处理import导入的esm模块，那么我们可以将模块文件打包成esm模块，然后指定module字段；由包的使用者来决定如何引用。

jsnext:main和module字段的意义是一样的，都可以指定esm模块的文件；但是jsnext:main是社区约定的字段，并非官方，而module则是官方约定字段，因此我们经常将两个字段同时使用。

在Webpack配置全解析中我们介绍到，mainFields就是webpack用来解析模块的，默认会按照顺序解析browser、module、main字段。

有时候我们还想要写一个同时能够跑在浏览器端和服务器端的npm包（比如axios），但是两者在运行环境上还是有着细微的区别，比如浏览器请求数据用的是XMLHttpRequest，而服务器端则是http或者https；那么我们要怎样来区分不同的环境呢？

除了我们可以在代码中对环境参数进行判断（比如判断XMLHttpRequest是否为undefined），也可以使用browser字段，在浏览器环境来替换main字段。browser的用法有以下两种，如果browser为单个的字符串，则替换main成为浏览器环境的入口文件，一般是umd模块的：

{
  "browser": "./dist/bundle.umd.js"
}

browser还可以是一个对象，来声明要替换或者忽略的文件；这种形式比较适合替换部分文件，不需要创建新的入口。key是要替换的module或者文件名，右侧是替换的新的文件，比如在axios的packages.json中就用到了这种替换：

{
  "browser": {
    "./lib/adapters/http.js": "./lib/adapters/xhr.js"
  }
}

打包工具在打包到浏览器环境时，会将引入来自./lib/adapters/http.js的文件内容替换成./lib/adapters/xhr.js的内容。

在有一些包中我们还会看到types字段，指向types/index.d.ts文件，这个字段是用来包含了这个npm包的变量和函数的类型信息；比如我们在使用lodash-es包的时候，有一些函数的名称想不起来了，只记得大概的名字；比如输入fi就能自动在编译器中联想出fill或者findIndex等函数名称，这就为包的使用者提供了极大的便利，不需要去查看包的内容就能了解其导出的参数名称，为用户提供了更加好的IDE支持。

发布哪些文件

在npm包中，我们可以选择哪些文件发布到服务器中，比如只发布压缩后的代码，而过滤源代码；我们可以通过配置文件来进行指定，可以分为以下几种情况：

存在.npmignore文件，以.npmignore文件为准，在文件中的内容都会被忽略，不会上传；即使有.gitignore文件，也不会生效。
不存在.npmignore文件，以.gitignore文件为准，一般是无关内容，例如.vscode等环境配置相关的。
不存在.npmignore也不存在.gitignore，所有文件都会上传。
package.json中存在files字段，可以理解为files为白名单。

ignore相当于黑名单，files字段就是白名单，那么当两者内容冲突时，以谁为准呢？答案是files为准，它的优先级最高。

我们可以通过npm pack命令进行本地模拟打包测试，在项目根目录下就会生成一个tgz的压缩包，这就是将要上传的文件内容。

项目依赖

在package.json文件中，所有的依赖包都会在dependencies和devDependencies字段中进行配置管理：

dependencies：表示生产环境下的依赖管理，–save 简写 -S；
devDependencies：表示开发环境下的依赖管理，–save-dev 简写 -D；

dependencies字段指定了项目上线后运行所依赖的模块，可以理解为我们的项目在生产环境运行中要用到的东西；比如vue、jquery、axios等，项目上线后还是要继续使用的依赖。

devDependencies字段指定了项目开发所需要的模块，开发环境会用到的东西；比如webpack、eslint等等，我们打包的时候会用到，但是项目上线运行时就不需要了，所以放到devDependencies中去就好了。

除了dependencies和devDependencies字段，我们在一些npm包中还会看到peerDependencies字段，没有写过npm插件的童鞋可能会对这个字段比较陌生，它和上面两个依赖有什么区别呢？

假设我们的项目MyProject，有一个依赖PackageA，它的package.json中又指定了对PackageB的依赖，因此我们的项目结构是这样的：

MyProject
|- node_modules
   |- PackageA
      |- node_modules
         |- PackageB

那么我们在MyProject中是可以直接引用PackageA的依赖的，但如果我们想直接使用PackageB，那对不起，是不行的；即使PackageB已经被安装了，但是node只会在MyProject/node_modules目录下查找PackageB。

为了解决这样问题，peerDependencies字段就被引入了，通俗的解释就是：如果你安装了我，你最好也安装以下依赖。比如上面如果我们在PackageA的package.json中加入下面代码：

{
    "peerDependencies": {
        "PackageB": "1.0.0"
    }
}

这样如果你安装了PackageA，那会自动安装PackageB，会形成如下的目录结构：

MyProject
|- node_modules
   |- PackageA
   |- PackageB

我们在MyProject项目中就能愉快的使用PackageA和PackageB两个依赖了。

比如，我们熟悉的element-plus组件库，它本身不可能单独运行，必须依赖于vue3环境才能运行；因此在它的package.json中我们看到它对宿主环境的要求：

{
  "peerDependencies": {
    "vue": "^3.2.0"
  },
}

这样我们看到它在组件中引入的vue的依赖，其实都是宿主环境提供的vue3依赖：

import { ref, watch, nextTick } from 'vue'

许可证

license字段使我们可以定义适用于package.json所描述代码的许可证。同样，在将项目发布到npm注册时，这非常重要，因为许可证可能会限制某些开发人员或组织对软件的使用。拥有清晰的许可证有助于明确定义该软件可以使用的术语。

借用知乎上Max Law的一张图来解释所有的许可证：

Untitled

版本号

npm包的版本号也是有规范要求的，通用的就是遵循semver语义化版本规范，版本格式为：major.minor.patch，每个字母代表的含义如下：

主版本号(major)：当你做了不兼容的API修改
次版本号(minor)：当你做了向下兼容的功能性新增
修订号(patch)：当你做了向下兼容的问题修正

先行版本号是加到修订号的后面，作为版本号的延伸；当要发行大版本或核心功能时，但不能保证这个版本完全正常，就要先发一个先行版本。

先行版本号的格式是在修订版本号后面加上一个连接号（-），再加上一连串以点（.）分割的标识符，标识符可以由英文、数字和连接号（[0-9A-Za-z-]）组成。例如：

1.0.0-alpha
1.0.0-alpha.1
1.0.0-0.3.7