現代前端庫開發指南系列（二）：使用 webpack 構建一個庫-有解無憂

前言

在前文中，我說過本系列文章的受眾是在現代前端體系下能夠熟練撰寫業務代碼的同學，因此本文在介紹 webpack 配置時，僅提及構建一個庫所特有的配置，其余配置請參考 webpack 官方檔案，

輸出產物

構建一個庫與構建一個一般應用最大的不同點在于構建完成后輸出的產物，

一般應用構建完成后會輸出：

一個 html 檔案
一個 js 入口 chunk 、若干子 chunk
若干 css 檔案
若干其它資源，如圖片、字體檔案等

雖然輸出的資源非常多，但實際上所有的依賴、加載關系都已經從 html 檔案開始一層一層定下來了，換句話說，這個 html 檔案實際上就是整個應用的入口，

一個庫構建完成后會輸出：

一個 CommonJS 格式的 js 檔案
一個未壓縮的 UMD 格式的 js 檔案
一個已壓縮的 UMD 格式的 js 檔案
可能包括若干的 css 檔案
可能包括若干的其它資源檔案

庫的入口分別是上面羅列的 js 檔案；你可能會奇怪，一個庫怎么會有3個入口檔案呢？莫急，且聽我一一道來，

CommonJS

CommonJS 是 Node.js 推行的一種模塊化規范，主要語法包括module.exports、require()等；而我們在使用 webpack 引入 npm 包時，實際上是處于 Node.js 環境，由此可知，這個 CommonJS 格式的入口 js 檔案（<庫名稱>.common.js）是供其它應用在 Node.js 環境下引入 npm 包使用的，由于在參考 npm 包時一般不會過多考慮 npm 包的體積（在構建自己的應用時如有需要可自行壓縮），且為了方便除錯，因此該 js 入口檔案是沒有經過壓縮的，

UMD

UMD 是一個模塊化規范大雜燴，除了兼容 CommonJS 外，它還兼容 AMD 模塊化規范，以及最傳統的全域變數模式，

這邊稍微介紹一下 AMD 規范， AMD 全稱 Asyncchronous Module Definition ，一般應用在瀏覽器端（這是與 CommonJS規范最大的不同點），最著名的 AMD 加載器是 RequireJS ，目前由于 webpack 的流行， AMD 這一模塊化方案已逐漸退出市場，

全域變數模式就很好理解了，就是把庫的入口掛載在一個全域變數（如window.xxx）上，頁面上的任何位置都能隨時取用，屬于最傳統的 js 插件加載方案，

由上可知， UMD 格式的入口 js 檔案，既可以用于參考 npm 包的場景（未壓縮的版本，即<庫名稱>.umd.js），也可以直接用于瀏覽器端（已壓縮的版本，即<庫名稱>.umd.min.js），

如何構建不同模塊化規范的庫檔案

目前， webpack 不支持同時生成多份入口 js 檔案，因此需要分多次來進行構建，

關鍵的 webpack 配置是：

CommonJS：output.libraryTarget: "commonjs2"
UMD：output.libraryTarget: "umd"

對于 UMD ，我們還需要設定全域變數名稱，即output.library: "LibraryName"，

為了壓縮構建出來的檔案，最簡單的方法是在 CLI 中呼叫 webpack 命令時帶上 mode 引數，如webpack --mode=production；這是因為當 mode 的值為production時， webpack 會自動啟用 UglifyJsPlugin 對原始碼進行壓縮，

輸出版本資訊

我在某公司作業時，該公司對第三方依賴抓得很緊，所有在專案里使用的第三方依賴都必須申請且審核通過后才可使用；且申請時是精確到具體版本的，未申請的軟體版本也一概不允許使用，某些第三方依賴無論在檔案內容上，還是在檔案名稱上，都沒有體現出版本號，這就對我們識別這類第三方依賴產生障礙，這是我們開發自己的庫時需要引以為戒的，

在構建庫時，我們完全可以利用 webpack 把庫的資訊直接輸出到檔案內容里，有了這“身份資訊”，用戶使用起來也會格外安心，

輸出庫版本資訊的方法是使用 webpack.BannerPlugin ，最簡單的使用方法如下：

const pgk = require('./package.json');
const banner = `
${pkg.name}
${pkg.description}\n
@version v${pkg.version}
@homepage ${pkg.homepage}
@repository ${pkg.repository.url}\n
(c) 2019 Array-Huang
Released under the MIT License.
hash: [hash]
`;

/* webpack 配置 */
{
    // ...其它配置
    plugins: [
        // ...其它 plugin 配置
        new webpack.BannerPlugin(banner);
    ]
}

最終生成出來的效果是：

/*!
 * 
 * vue-directive-window
 * Vue.js directive that enhance your Modal Window, support drag, resize and maximize.
 * 
 * @version v0.7.5
 * @homepage https://github.com/Array-Huang/vue-directive-window
 * @repository git+https://github.com/Array-Huang/vue-directive-window.git
 * 
 * (c) 2019 Array-Huang
 * Released under the MIT License.
 * hash: dc6c11a1e50821f4444a
 * 
 */

source map

如果庫的用戶是直接通過在瀏覽器里加載你的庫來使用的話，那么提供一份 source map 檔案是非常有必要的；這是因為你的庫在經過 webpack 構建，甚至壓縮后，與源代碼已經大相徑庭了，用戶將難以在瀏覽器中進行除錯；但如果你能為自己的庫附上一份 source map ，瀏覽器開發者工具會呼叫 source map 來幫助決議，用戶的除錯體驗會更接近于除錯庫的原始碼，

相應的 webpack 配置為：

// webpack 配置
{
    // ...其它配置
    devtool: 'cheap-module-source-map'
}

webpack 支持多種型別的 source map ，不同型別的 source map 在生成速度、支持功能（如 babel ）、除錯位置偏移等問題上均有不同表現，我這邊只做推薦：

開發環境：cheap-module-eval-source-map
生產環境：cheap-module-source-map

關于其它型別的 source map ，請查看 webpack 官方檔案的 devtool 章節，

排除第三方依賴

與一般應用不一樣，在開發庫的時候，我們應盡量避免引入第三方庫（構建程序中使用的工具鏈除外），因為這些第三方庫會讓我們寫的庫的大小猛增；很可能會出現這樣的情況：我們自己寫的小功能只有幾百行代碼的邏輯，構建出來的庫卻有幾百k，那這樣的庫意義就不大了，

但我們的確也很難避免使用第三方庫，那該咋辦呢？

// webpack 配置
{
    // ...其它配置
    externals: {
        lodash: {
            commonjs: 'lodash',
            commonjs2: 'lodash',
            amd: 'lodash',
            root: '_'
        }
    }
}

使用上述配置后，我們構建出來的庫中就不會包含配置中指定的第三方庫（例子中為lodash）了，下面來一一詳解：

commonjs和commonjs2項都是指明用戶在 node.js 環境下使用當前庫時，以 CommonJS 的方式來加載名為lodash的 npm 包，
amd項表示在瀏覽器中加載運行本庫時，本庫會試圖以 AMD 的方式來加載名為lodash的 AMD 模塊，
root項表示在瀏覽器中加載運行本庫時，本庫會試圖取全域變數window._（通過<script>標簽加載lodash.js時， lodash 會把自己注入到全域變數window._中），

與一般應用不一樣的 externals 配置

在一般應用中，你或許會看到這樣的 externals 配置：

// webpack 配置
{
    // ...其它配置
    externals: {
        lodash: '_'
    }
}

這樣的 externals 配置方式意味著：無論在什么環境，都要取_這個全域變數；如果當前是在一般應用且確定已經使用<script>來加載指定的第三方庫（比如 jQuery、 Vue 等核心庫，的確很常以這種方式來加載），當然大可直接這樣用；但我們作為庫的作者，應提供更寬松更靈活的使用方式，

完整的 webpack 配置示例

由于構建不同模塊化規范的庫需要不同的 webpack 配置（其實也只是稍有不同）來進行多次構建，因此本文只針對構建 UMD 格式且已壓縮這一場景來展示最簡單的 webpack 配置示例；如果想知道如何更有效率地拼接 webpack 配置，請看 micro-schema-validator 專案的 webpack 組態檔，

// webpack.config.js
const webpack = require('webpack');
const pkg = require('./package.json'); // 把 package.json 作為資訊源
const banner = `
${pkg.name}
${pkg.description}\n
@version v${pkg.version}
@homepage ${pkg.homepage}
@repository ${pkg.repository.url}\n
(c) 2019 Array-Huang
Released under the MIT License.
hash: [hash]
`;

module.exports = {
  entry: `${__dirname}/index.js`,
  devtool: 'cheap-module-source-map',
  output: {
    path: `${__dirname}/dist`, // 定義輸出的目錄
    filename: 'micro-schema-validator.min.js', // 定義輸出檔案名
    library: 'MicroSchemaValidator', // 定義暴露到瀏覽器環境的全域變數名稱
    libraryTarget: 'umd', // 指定遵循的模塊化規范
  },
  /* 排除第三方依賴 */
  externals: {
    lodash: {
  	  commonjs: 'lodash',
      commonjs2: 'lodash',
      amd: 'lodash',
      root: '_'
    }
  },
  module: {
    rules: [
      {
        test: /(\.jsx|\.js)$/,
        loader: 'babel-loader',
        exclude: /(node_modules|bower_components)/
      },
      {
        test: /(\.jsx|\.js)$/,
        loader: 'eslint-loader',
        exclude: /(node_modules|bower_components)/
      }
    ]
  },
  plugins: [
  	new webpack.BannerPlugin(banner) // 輸出專案資訊
  ]
};

利用 vue-cli 定制并管理 webpack 配置

對于 Vue 生態的庫，如 Vue 組件、Vue 自定義指令等，可以使用 vue-cli （本文特指 vue-cli 3.0 后的版本）根據你的需求來定制 webpack 配置，可定制內容包括：

是否啟用 Babel
是否接入 TypeScript 語法
是否支持 PWA
是否使用 Vue-Router 和 Vuex
是否使用 CSS 前處理器，并可選擇具體的 CSS 前處理器，包括 Sass / Less / Stylus
是否使用 ESLint 和 Prettier
是否接入單元測驗和端對端測驗(E2E)

定制完成后， vue-cli 將生成一個種子專案，該專案可執行（包括本地開發和構建生產環境的包）但沒有實際內容（實際內容不還得由你來寫嘛哈哈），與一般的腳手架工具相比， vue-cli 除了可以生成 webpack 配置外，還將持續對其進行管理和維護，如：

提供一個統一的自定義配置的入口；過往，我們為了達到自定義配置的目的，往往會直接在腳手架工具生成出來的 webpack 配置上直接進行修改，這樣會導致修改點非常分散，難以讓自定義的 webpack 配置在其它專案復用；而使用 vue-cli 后，所有對 webpack 配置的修改點都被集中管理起來了，需要復用的話，直接把這自定義組態檔(vue.config.js)遷移到別的專案即可，
提供持續更新 webpack 配置的機制；假如現在有一個開源庫，我為了達到自己的目的，肆意在庫原始碼上修改，那么當我需要升級該開源庫的時候可就犯難了，因為這會把我之前做的修改都覆寫掉；同理可得，vue-cli 由于統一了自定義配置的入口，并且是在每次運行專案（運行專案也是通過執行 vue-cli 的命令而非 webpack）時動態渲染 webpack 配置的，因此專案的 webpack 配置可以隨著 vue-cli 的升級而不斷升級了，
提供持續更新 webpack 工具鏈的機制；眾所周知， webpack 工具鏈中包含了大量的第三方開源庫，如 Babel 、ESLint 等，這些開源庫也都是在不斷更新當中，在這個程序中，必然會不斷產生 Breaking Change ，所幸 vue-cli 通過自身升級——不斷修改 webpack 配置來達到適配最新版第三方開源庫的目的，而我們的專案也可以以極小的代價（升級 vue-cli 本身）來獲取 webpack 工具鏈的不斷更新，

vue-cli 自定義配置示例

摘自 vue-directive-window 專案的 vue.config.js 檔案：

const webpack = require('webpack');
const pkg = require('./package.json');

const banner = `
${pkg.name}
${pkg.description}\n
@version v${pkg.version}
@homepage ${pkg.homepage}
@repository ${pkg.repository.url}\n
(c) 2019 Array-Huang
Released under the MIT License.
hash: [hash]
`;

module.exports = {
  chainWebpack: config => {
    config.output.libraryExport('default');
    config.plugin('banner').use(webpack.BannerPlugin, [
      {
        banner,
        entryOnly: true,
      },
    ]);
  },
};

看起來是不是比上文中最基礎的 webpack 配置還要簡潔呢？當專案的架構逐漸豐富起來后，這個差距將不斷拉大，

實體專案代碼介紹

在我的作業生涯中，我寫的絕大部分庫都是為公司的專案寫的，很可惜無法帶出來，但我會以我最近寫的兩個開源庫：javascript-library-boilerplate 和 vue-directive-window 來作為實體專案代碼來輔助介紹，

javascript-library-boilerplate

javascript-library-boilerplate 是一個現代前端生態下快速構建 javascript 庫的腳手架（或稱種子專案，或稱示例代碼，看你理解了），本庫支持 GitHub 的 repository templates 功能，你可以直接在專案首頁點擊 Use this template 來直接套用本腳手架的代碼來創建你自己的 javascript 庫，

vue-directive-window

vue-directive-window 是一個可以快速讓模態框(modal)支持類視窗操作的增強庫；類視窗操作主要包括三大類：拖拽移動、拖拽調整視窗尺寸、視窗最大化； vue-directive-window 支持以 Vue 自定義指令或是一般 js 類的方式來呼叫，

vue-directive-window 相對于 javascript-library-boilerplate 來說，更貼近 Vue 生態圈，如果你最近想為 Vue 生態圈添磚加瓦，不妨參考一下本專案，

實體專案代碼介紹

我會以我最近寫的兩個開源庫：javascript-library-boilerplate 和 vue-directive-window 來作為實體專案代碼來輔助介紹，

javascript-library-boilerplate

vue-directive-window

vue-directive-window 相對于 javascript-library-boilerplate 來說，更貼近 Vue 生態圈，如果你最近想為 Vue 生態圈添磚加瓦，不妨參考一下本專案，

系列文章目錄（同步更新）

《現代前端庫開發指南系列（一）：融入現代前端生態》
《現代前端庫開發指南系列（二）：使用 webpack 構建一個庫》
《現代前端庫開發指南系列（三）：從說明檔案看庫的前世今生》

想要閱讀更多我的技術文章？請到我的 GitHub 博客 Array-Huang/blog 來，如果對您有幫助的話請 Star&Watch 走一波哈(〃^ω)

轉載請註明出處，本文鏈接：https://www.uj5u.com/qiye/162718.html

標籤：JavaScript

上一篇：jTopo HTML5 Canvas 畫圖組件

下一篇：復選框全選/全部選