browserify 中文文档与使用教程

大概介绍

1. 浏览器端的前端打包工具
2. 主要用于在浏览器中使用 npm 包，最终会转换为 commonJS (require) 类似方式，在浏览器使用
3. 方便模块细分，每个模块自成，通过 require 引用其他模块
4. 基于流 Stream
5. 旧时代产物，尽管也能勉强处理 css（CSS bundlers），html（brfs），但是不太友好，且年久失修

阅读此篇，大概可以较好使用 browserify，以及将其用在合适的地方

此外，文中带 删除线 的内容，因相对的内容过时，阅读意义不大，可简单跳过

大概分析

以 nums.js，demo.js，build 文件做大概分析

nums.js

var uniq = require('uniq'); // uniq 为 npm 依赖包
var nums = [ 5, 2, 1, 3, 2, 5, 4, 2, 0, 1 ];
module.exports = nums

demo.js

const nums = require('./nums')
console.log(nums)

build

const browserify = require('browserify')
const fs = require('fs')
browserify(['./src/demo'])
	.bundle()
	.pipe(fs.createWriteStream('./build/demo.js'))

build 后文件

通过 detective 进行依赖查找，后落地为以下文件

(function(){function r(e,n,t){function o(i,f){if(!n[i]){if(!e[i]){var c="function"==typeof require&&require;if(!f&&c)return c(i,!0);if(u)return u(i,!0);var a=new Error("Cannot find module '"+i+"'");throw a.code="MODULE_NOT_FOUND",a}var p=n[i]={exports:{}};e[i][0].call(p.exports,function(r){var n=e[i][1][r];return o(n||r)},p,p.exports,r,e,n,t)}return n[i].exports}for(var u="function"==typeof require&&require,i=0;i<t.length;i++)o(t[i]);return o}return r})()({
      1:[function(require,module,exports){
          "use strict"

          // 为避免内容过长，此部分略去

          module.exports = unique

      },{}],
      2:[function(require,module,exports){
          const nums = require('./nums')
          console.log(nums)
      },{"./nums":3}],
      3:[function(require,module,exports){
          var uniq = require('uniq');
          var nums = [ 5, 2, 1, 3, 2, 5, 4, 2, 0, 1 ];

          module.exports = nums
      },{"uniq":1}],
    },
    {},
    [2]);

build 后文件运转方式

上面的编译后文件，顶部的压缩代码，来源于 browser-pack

// modules are defined as an array
// [ module function, map of requireuires ]
//
// map of requireuires is short require name -> numeric require
//
// anything defined in a previous bundle is accessed via the
// orig method which is the requireuire for previous bundles

(function() {

function outer(modules, cache, entry) {
    // Save the require from previous bundle to this closure if any
    var previousRequire = typeof require == "function" && require;

    function newRequire(name, jumped){
        if(!cache[name]) {
            if(!modules[name]) {
                // if we cannot find the module within our internal map or
                // cache jump to the current global require ie. the last bundle
                // that was added to the page.
                var currentRequire = typeof require == "function" && require;
                if (!jumped && currentRequire) return currentRequire(name, true);

                // If there are other bundles on this page the require from the
                // previous one is saved to 'previousRequire'. Repeat this as
                // many times as there are bundles until the module is found or
                // we exhaust the require chain.
                if (previousRequire) return previousRequire(name, true);
                var err = new Error('Cannot find module \'' + name + '\'');
                err.code = 'MODULE_NOT_FOUND';
                throw err;
            }
            var m = cache[name] = {exports:{}};
            modules[name][0].call(m.exports, function(x){
                var id = modules[name][1][x];
                return newRequire(id ? id : x);
            },m,m.exports,outer,modules,cache,entry);
        }
        return cache[name].exports;
    }
    for(var i=0;i<entry.length;i++) newRequire(entry[i]);

    // Override the current require with this new one
    return newRequire;
}

return outer;

})()

上方的编译代码，即相当于：

// step 1
newRequire(2)

// step 2
(function(require,module,exports){
	const nums = require('./nums')
	console.log(nums)
}).call({}, function(x){
	// name is 2
	// x is './nums'
	// id is 3
    var id = modules[name][1][x];
    return newRequire(id ? id : x);

// 至于说，为什么这里要增加 outer, modules, cache, entry 这样的无用参数
// 可参考：https://github.com/browserify/browser-pack/issues/82
// 简单理解为：有其他用途
}, { exports:{} }, {}, outer, modules, cache, entry)

// step 3, 4, 5, etc...

以此类推，通过 newRequire 以及相应的 modules 编号，达到代码执行的目的。

多入口文件编译

const browserify = require('browserify')
const fs = require('fs');

// 指定入口即可
['./src/demo-1', './src/demo-2'].forEach(f => {
  browserify(f).bundle().pipe(fs.createWriteStream(f.replace('./src', './build') + '.js'))
})

配置

entries

同 browserify 第一个参数，files

basedir

如果 entries / files 为 stream，需要指定 basedir 来让 browserify 可以处理内容中的相对路径

默认为 . 即当前脚本运行目录

require

数组，通过模块名或文件路径指定需要打包到bundle中的其他模块

browserify('demo-4', {
  basedir: './src',
  require: ['./demo-3-module-2'],
})

适用于一些全局的处理，又没有模块依赖的内容

例如 ./demo-3-module-2 内容：

window.demo3Func = function (n) {
  return n + 1
}

通过 参数 opts.require 方式引入，那么所有被打包的文件，都会有此部分代码

debug

debug 为 true 时，会将 sourcemap 添加到包的末尾

ignoreMissing

默认为 false，即如果 require 的模块不存在时，会报错；如果设置为false，即忽略报错

noParse

一个数组，跳过数组中每个文件的所有 require 和全局解析

适用于jquery或threejs等巨型、无需解析的库，避免解析耗时过长

{
  noParse: ['jquery']
}

transform

一个数组，用于内容的相应转换。例如使用 uglifyify

browserify(f, {
    transform: ['babelify'], // babel 配置在 .babelrc 中指定
})
// or
browserify(f, {
    transform: [['babelify', { presets: ['@babel/preset-env'] }]],
})

数组的元素可以为字符串，或者数组（该数组第一项为使用的transform组件，第二项为该组件配置项）。

下方 plugin 等，同理。

ignoreTransform

一个数组，用于过滤不需要做 transform 的 transform 控件

browserify(f, {
    transform: [['babelify', { presets: ['@babel/preset-env'] }]],
    ignoreTransform: ['babelify'],
})

也就不会进行 babelify transform

这个参数没什么作用，其实如果不想进行转换，不把它放入 transform 内就好，不需要多此一举在 transform 中添加，又在 ignoreTransform 定义不进行转换

plugin

插件数组。主要用于一些更高级的插件配置，增强 browserify 功能。

详见：plugins 或者下方一些示例

extensions

参数可为字符串或数组。默认是 ['.js', '.json']，可以补充 .ts, .jsx 等等

paths

一个目录数组，用于在查找未使用相对路径引用的模块时浏览搜索，可以是绝对的或相对于basedir。调用browserify命令时，等效设置 NODE_PATH 环境变量

browserify('./src/demo', {
    basedir: './',
    transform: [['babelify', { presets: ['@babel/preset-env'] }]],
    paths: ['src'], // ./src 下的模块引用都不需要使用相对路径引用
})

browserify('./demo', {
    basedir: './src',
    transform: [['babelify', { presets: ['@babel/preset-env'] }]],
    paths: ['test'], // ./src/test 下的模块引用都不需要使用相对路径引用
})

例如：原来 require('./a') 可以直接写为 require('a')

commondir

没什么作用的参数，要么不传递，要么传递 false

目前看 browserify index.js:616 只会在 builtIns 为数组时，会将 basedir 设置为 /

可能对 sourcemap 有一点影响，其他没什么作用

fullPaths

布尔值，默认为 false，参考上方的分析代码，对应模块会被标记为数字 id，例如： ./nums: 0

如果设置为 true，不会转换为 id，而是以绝对路径形式展示。例如："./nums":"/Users/xxx/xxx/xxx/browserify-demo/src/nums.js"。官网文档描述其对于保留生成包的原始路径很有用，但是如果在生产环境下，需要设置为 false，否则可能会暴露一些信息

standalone

// beep.js
var shout = require('./shout.js');
module.exports = function beep() {
  console.log(shout('beep'));
}

// shout.js 
module.exports = function shout(str) {
  return str.toUpperCase() + '!';
};

// build.js
var fs = require('fs');
var browserify = require('browserify');
var b = browserify('./src/beep.js', { standalone: 'beep-boop' });
b.bundle().pipe(fs.createWriteStream('./build/demo-5.js'));

如果使用 standalone: 'beep-boop' 最终打包出来的内容，就不是 browser-pack 做的包裹，而是

这个 umd/template 做的包裹，主要用来处理 requireJS 类似的调用方式，包括在全局下增加 变量。例如上方最终在全局下增加的 beepBoop（驼峰） 变量。

所以作为 standalone（“独立”）的模块，就目前9012年来说，没有什么意义。

参考：Standalone Browserify Builds

externalRequireName

文档不全，没什么用途，不要使用。需要搭配 prelude 参数（文档未描述）。参见：

1. test/multi_bundle_unique
2. opts.externalRequireName does not work in standalone mode

browserField

如果在项目中 package.json 中配置 browser 字段

"browser": {
    "ccc": "./src/ccc.js"
},

在代码源文件中，require('ccc') 会自动被处理成 require('./src/ccc.js')

功能和 paths 类似，但是其主要用来替换原有的模块，而不是 alias 作用

而优先级方面，paths 的设置更高。不过，在使用上需要尽量避免paths 和 browserField 设置相同模块的情况，以免造成一些歧义和不可控的现象

为 false 时，将忽略 package.json 中这个字段

builtins

设置要使用的内置函数列表，默认情况下为 lib/builtins.js

可为 false、array、object

如果设置为 false，不会进行任何 Node 相关内容的设置

如果设置为 array，可以设置为 lib/builtins.js 对应的 key name，例如： ['assert', 'buffer'] 代表只将此两部分作为内置内容

如果设置为 Object，将直接替换掉默认的 lib/builtins.js，而采用用户的配置

详见：builtins 代码逻辑

bare

例如：

console.log(__dirname)
console.log(process.env)

默认为 false，会将 __dirname、process.env 设置为浏览器可运行的内容 （包含 builtins ）。process.env 会被设置为 node-process

设置为 true 时，同 builtins = false, commondir = false。创建一个不包含 Node builtins 的bundle，并且不设置除 __dirname 和 __filename 之外的全局 Node 变量。即 process.env 还是 process.env。而这样的处理，如果模块内有使用相关 Node 模块，浏览器端运行会直接报错

node

默认为 false

设置为 true 时，创建一个在 Node 中运行的bundle，不使用浏览器版本的依赖项。与传递 {bare：true，browserField：false} 相同。这个参数，一般也用不上，如果在 node 运行，也便不需要 browserify

detectGlobals

默认为 true，只在 bare 为 false 时作用。例如：

console.log(__dirname)
console.log(process.env)

会进行模块扫描，上方 __dirname 和 process.env 的设置，是先通过检测，后设置，不设置其他多余内容。但是这样，检测的时间会长一些

如果将其设置为 false，类似 bare 设置为 true，不会进行 __dirname 和 process.env 的设置

insertGlobals

默认为 false，即不直接设置所有 Node 相关的内容，而是通过 detectGlobals=true 按需设置

如果设置为 true，会始终插入 Node 相关内容，而不做相应模块分析检测。提高了效率，但是打出来的包，内容也更大。但是detectGlobals 必须为 true 才能工作

其他一些作用的需要条件详见：globalTr

insertGlobalVars

会被作为 opts.vars 传递给 insert-module-globals

格式可参考 defaultVars

{
  detectGlobals: true,
  insertGlobalVars: {
    forTest: function () {
      return '1111';
    }
  },
}

注意：detectGlobals 需要为 true，这样才能检测文件内的 forTest 变量，并做相应设置

bundleExternal

默认为 true，代表内置的 process、buffer 是否可以设置进去

详见：index.js#L608

例如：

{
  detectGlobals: true,
  insertGlobal: true,
  bundleExternal: false,
  insertGlobalVars: {
    xxx: function () {
      return '1111';
    }
  },
}

即使 detectGlobals, insertGlobal 都为 true，也不会进行 process 和 buffer 的设置

方法

b.add(file, opts)

同 opts.entries 参数

b.require(file, opts)

同 opts.require 参数

b.ignore(file)、b.external(file)、b.exclude(file)

这三个方法，都是用来将 打包文件内的某个/某几个模块 移除编译内容，参数可为 string、array

三个方法的区别，文档也没说清（browserify 文档太过简略）。大概如下：

const $ = require('jquery')
$('body').css('background', 'red')

// ignore
({
  1:[function(require,module,exports){
  },{}],
  2:[function(require,module,exports){
    const $ = require('jquery')
    $('body').css('background', 'red')
  },{"jquery":1}],
}, {},[2]);

// exclude
({
  1:[function(require,module,exports){
  const $ = require('jquery')
  $('body').css('background', 'red')
  },{"jquery":undefined}]
}, {},[1]);

// external
({
  1:[function(require,module,exports){
  const $ = require('jquery')
  $('body').css('background', 'red')
  },{"jquery":"jquery"}]
},{},[1]);

理解大概是：

1. ignore 代表忽略，如果内部引用了，会将其模块作为作为空模块处理，模块的位置还在
2. exclude 会将该模块直接移除，并且如果 require了的话，值为 undefined
3. external 会将该模块移除，但是对应的模块引入，还是会在运行时进行 require(name) 的形式，由全局的 require 进行其他模块依赖引入

这么看，也只有 external 具备一定的实用性

b.transform(tr, opts={})

同 opts.transform

b.transform('babelify', { presets: ['@babel/preset-env'] })

// 同
browserify('./src/demo', {
  transform: [['babelify', { presets: ['@babel/preset-env'] }]],
})

b.plugin(plugin, opts)

同 opts.plugin

b.bundle(cb)

将内容以及内容内部的 reuqire 内容，一并打包进一个文件内

创建了一个可读流，用于 pipe 进可写流文件。例如：

b.bundle().pipe(fs.createWriteStream('./build/demo-7.js'))

callback 为可选项，参数为 err, buf，buf 为文件 buffer 内容，因此也就可以基于 buf 内容进行一些其他处理

b.pipeline

一个属性，使用 labeled-stream-splicer，个人简单理解为将内容拆分为不同的分段，通过流的方式进行传递

一般来讲，如果不是写插件之类东西，单纯使用 browserify 层面上来说，用不到

对应的，browserify 内置了一些 label

'record' - save inputs to play back later on subsequent bundle() calls
'deps' - module-deps
'json' - adds module.exports= to the beginning of json files
'unbom' - remove byte-order markers
'unshebang' - remove #! labels on the first line
'syntax' - check for syntax errors
'sort' - sort the dependencies for deterministic bundles
'dedupe' - remove duplicate source contents
'label' - apply integer labels to files
'emit-deps' - emit 'dep' event
'debug' - apply source maps
'pack' - browser-pack
'wrap' - apply final wrapping, require= and a newline and semicolon

可以通过 b.pipeline.get(label) 的方式获取，并对其进行相应的处理

b.reset(opts)

将流恢复到 bundle() 前的状态，主要用于需要多次 bundle() 的场景

实际每次 bundle() 调用后，reset() 都会自动执行，所以这个方法在实际使用过程中，可能也没有太大的用处

var b = browserify('./src/beep.js', {
  debug: true,
  commondir: false,
  builtins: [],
});

b
.transform('uglifyify', { global: true })
.bundle().pipe(fs.createWriteStream('./build/demo-6.js'));

setTimeout(() => {
  b.bundle().pipe(fs.createWriteStream('./build/demo-7.js'));
}, 2000)

上方 打包出来 demo-6、demo-7 内容是完全一致的

或者参考 browserify/test/reset.js

其他工具

更多的工具，可见 awesome-browserify#tools，此处取一部分代表性内容

budo

启动 http 服务器，进行相应 browserify 打包

budo ./beep.js --live --open

如果 index.html 内，引用 <script src="./beep.js"></script>，最终启动的服务便是这个 index.html，以及实时打包的 http://127.0.0.1:9966/beep.js 文件

内容类似如下：

<script type="text/javascript" src="/budo/livereload.js" async="" defer=""></script>
<script src="beep.js"></script>

envify

给 process.env 添加环境变量替换

b.transform(envify({
  // 将 process.env 其他字段设置为 undefined
  _: 'purge',
  // process.env.NODE_ENV 会被自动替换为 'development'，而不是在运行时获取 process.env.NODE_ENV 值
  NODE_ENV: 'development'
}))

babelify

因为 browserify 只处理文件相关依赖引入，不处理文件的 es6 转换，因此如果需要使用 es6、es7 语法，需要经过 babelify 进行转换

['./src/demo-1', './src/demo-2'].forEach(f => {
  browserify(f)
    .transform('babelify', { presets: ['@babel/preset-env'] })
    .bundle()
    .pipe(fs.createWriteStream(f.replace('./src', './build') + '.js'))
})

tsify

因为 browserify 只处理文件相关依赖引入，如果想要使用 typescript 编写浏览器端代码，需要进行相应转换

但是原则上，其实也可以通过 gulp-babel 的方式进行处理，因为：

1. babel 7 支持了 typescript 的转换
2. gulp-babel 也是基于流

或者，通过 gulp-typescript 进行处理，理由同上

uglifyify

代码丑化

['./src/demo-1', './src/demo-2'].forEach(f => {
  browserify(f)
    .transform('uglifyify', { global: true })
    .bundle()
    .pipe(fs.createWriteStream(f.replace('./src', './build') + '.js'))
})

tinyify

b.plugin('tinyify', {
  env: {
    PUBLIC_PATH: 'https://mywebsite.surge.sh/'
  }
})

以下用到的插件的整合版本

b
    .transform('unassertify', { global: true })
    .transform('envify', { global: true })
    .transform('uglifyify', { global: true })
    .plugin('common-shakeify')
    .plugin('browser-pack-flat/plugin')
    .bundle()
    .pipe(require('minify-stream')({ sourceMap: false }))
    .pipe(fs.createWriteStream('./output.js'))

watchify

检测改动，自动编译

作为插件：

const b = browserify('./demo-2', {
  basedir: 'src',
  debug: true,
  paths: ['./'],
  fullPaths: true,
  plugin: [['watchify', {
    delay: 100,
    ignoreWatch: ['**/node_modules/**'],
    poll: false
  }]]
})

b.on('update', bundle)
bundle()

function bundle(x) {
  console.log(x)
  b
    .transform('babelify', { presets: ['@babel/preset-env'] })
    .transform('uglifyify', { global: true, sourceMap: true })
    .bundle()
    .on('error', console.error)
    .pipe(fs.createWriteStream('./build/demo-5.js'))
}

或者

const b = watchify(browserify('./demo-2', {
  basedir: 'src',
  debug: true,
  paths: ['./'],
  fullPaths: true,
}), {
  delay: 100,
  ignoreWatch: ['**/node_modules/**'],
  poll: false
})

b.on('update', bundle)
bundle()

function bundle(x) {
  console.log(x)
  b
  .transform('babelify', { presets: ['@babel/preset-env'] })
  .transform('uglifyify', { global: true, sourceMap: true })
  .bundle()
  .on('error', console.error)
  .pipe(fs.createWriteStream('./build/demo-5.js'))
}

附：Fast browserify builds with watchify

css-modulesify

如其名 css-modulesify，使用它可以在 js 中 require css 内容

brfs

使用 brfs，可以达到 js 中 require html 类似的效果

var html = fs.readFileSync(__dirname + '/robot.html', 'utf8');

// 最终转换为

var html = "<b>beep boop</b>\n";

browserify-hmr

browserify 本身是基于流，效率比较高。热更新的用处不大，而且根据 README.md 内作者描述，此插件还是存在不少问题

factor-bundle

拆包：将 x、y 共用部分，打包进 common.js，有一定的实用性

browserify([ './files/x.js', './files/y.js' ])
  .plugin('factor-bundle', { outputs: [ 'bundle/x.js', 'bundle/y.js' ] })
  .bundle().pipe(fs.createWriteStream('bundle/common.js'))

和 gulp 对比

gulp 缺陷

1. gulp 没有相关 require 引用处理的能力

2. 如果单纯只用 gulp，相应模块之间的拆分，只能通过全局变量的方式进行管理，相对来说比较混乱。例如：

   // a module
   window.lib.someFunc = xxx
   
   // b module
   window.lib.someFunc()
   
   // 打包
   gulp.src(['a.js', 'b.js'])

browserify 优势与缺陷

优势

1. 而如果用 browserify，因为模块之间的引用，通过 require 完成。与 node 模块编写方式一致，此外，入口文件只需要一个。

   // a module
   exports.someFunc = xxx
   
   // b module
   const { someFunc } = require('./a')
   someFunc()
   
   browserify(['./b'])
     .bundle()
     .pipe(fs.createWriteStream('./build/b.js'))

缺陷

1. 以 js 作为入口文件，缺乏 css、html 等处理能力

一起使用

而因为他们都是基于流的处理，因此可以通过流相关的工具，例如 vinyl-source-stream、through2 进行相应转换，来达到共用的目的

结语

基于其与 gulp 的比较，个人认为 最好的方式 是在 gulp 中集成 browserify 功能（将 browserify 作为 gulp 的一个扩展），只用于 require 相关处理

这样，可以结合双方的优点，并且避免了双方的缺陷

而像 babel、typescript 相关转换以及 sourcemap、minify 等等功能，交给 gulp 相关插件

gulp 对应的 browserify 插件：gulp-bro

代码也比较简单，仅仅是对于流进行了相应转换 gulp-bro 源码

最后，此文对 browserify 做的部分介绍，相关配置、插件其实已经过时而没有太大存在和深究的意义

此外，

1. browserify 的配置很多，而且很多都重复功能
2. browserify 基本上也只有浏览器前端才会需要使用，也就没必要用到太多的无用配置。例如：bare, builtins, detectGlobals, insertGlobals, insertGlobalVars 等等配置都应该移除
3. 原 gulp-browserify 已经停止维护，像其他的一些 browserify 工具，也都很少再有更新