NPM 包管理与发布

3,463 阅读3分钟

最近试着发布了一两个NPM包,一个是mapbox 的一些插件类,另一个是vudio,一个音频可视化的库。简单记录下NPM 包管理的一些操作,主要是发布包的一些概念和注意点

Vudio snapshot

关键字段

首先,我们得有一个有package.json 文件的文件夹,其中有几个关键字段需要注意。

NPM包nameversion 是必须的,version 得是符合semversion 规范的,也就是 major.minor.patch 三个数字组成,大版本小版本和patch。比如每次 npm publish 之前可以通过npm version minor 去自动增加一个小版本数字,会自动修改package.json 中的 version 值。也就是说最好不要手动改 package.json文件中的version 字段。

比如vudio 的版本号本来是 2.0.3, 脚本自动增加版本号后,再通过 npm version 查看当前的版本信息

npm version minor
npm version
> { vudio: '2.0.4',
  npm: '5.5.1',
...
}

npm publish

main,browser 字段

以我的vudio 包package文件为例

// package.json of my NPM package Vudio
{
  "name": "vudio",
  "version": "2.0.4",
  "description": "visualization audio using AudioContext and Canvas",
  "main": "umd/vudio.js",  // 如果是esModule 或者node.js的包,把入口文件填这里
  "browser": "umd/vudio.js",  // 如果这个包针对浏览器环境,那填这里
  "files": [
    "umd",
    "*"
  ]
}

这几个字段比较有用,main字段标识了你 npm 包的入口,比如别人安装了我的包, 在 nodejs 程序中 require 我导出的模块对象,实际上就会去packge.json中查找 main 字段,到底指的是哪个js 文件

var Vudio = require('vudio')
// 实际上等效于
var Vudio = require('vudio/umd/vudio.js')

通过require或者import引入NPM包时,是读取 main 字段来获取入口文件地址。这主要针对符合common.js和esModule 模块规范的第三方NPM 包。如果你要发布的NPM 包只能在 browser 环境下运行,比如要依赖 window,DOM这类浏览器环境下的要素。那可以直接给 browser 字段指定你的 umd 文件地址,也就是通用模块定义文件。

UMD 模块定义方式

这种导出模块的典型特征就是适配各种运行环境,不管是浏览器还是nodejs环境,都可以顺利导出模块,优雅适配

// 典型的umd 模块导出
(function(factory){
    if (typeof exports === 'object') {  // 支持Common.js 
         module.exports = factory();
    } else if (typeof define === 'function' && define.amd) {  // 支持AMD
         define(factory); 
    } else {
         window.Vudio = factory();   // 浏览器环境
    }

 })(function() {
    /// 你的功能
    function Vudio(){
    //// .....
    }
    return Vudio
})

这样 npm publish 之后就可以在npm仓库里查到你的包了。有个问题就是publish 之前得 npm login 下,另外要确保你的 package name 是全网唯一,不然会提示 403,没有权限提交。

提交给CDN

除了把NPM包发布给 官方仓库,还可以顺手提交给 unpkg.com/ 这样的 CDN 网站,实际上是Cloudflare 提供的CDN 服务。 主要做到两点:

  • 添加 umd (or dist) 文件夹到 .gitignore 文件中,也就是说在git repo 里面忽略这个用于发布包的文件夹
  • 把 umd 文件夹地址添加到package.json的 files array 字段中

files字段指的是,你要把哪些文件、文件夹包含在NPM包里面。这样你 npm publish 的时候只会把这部分文件(通常是必要的,无个人数据的)打包 tgz 提交给npm 仓库。

配置完成后,npm publish 之后就可以在unpkg CDN 上查到自己的包了. 一般地址是 unpkg.com/:package@:version/:file

参考文档:

创建和发布NPM包的官方文档