webpack 從 v1 遷移到 v2

resolve.root, resolve.fallback, resolve.modulesDirectories

上述配置項被一個單獨的配置項 resolve.modules 取代。詳見 resolving。

resolve: {
-   root: path.join(__dirname, "src")
+   modules: [
+     path.join(__dirname, "src"),
+     "node_modules"
+   ]
  }
resolve.extensions

此配置項再也不須要傳一個空字符串。此行爲被遷移到 resolve.enforceExtension。詳見 resolving。

resolve.*

還有更多的變化，因爲不經常使用，不在這裏詳細列出。詳見 resolving。

module.loaders 改爲了 module.rules

舊的 loader 配置被更強大的 rules 系統取代，後者容許配置 loader 以及其餘更多項。爲了兼容舊版，module.loaders 語法被保留，舊的屬性名依然能夠被解析。新的命名約定更易於理解而且是升級配置使用 module.rules 的好理由。

module: {
-   loaders: [
+   rules: [
      {
        test: /\.css$/,
-       loaders: [
+       use: [
          {
            loader: "style-loader"
          },
          {
            loader: "css-loader",
-           query: {
+           options: {
              modules: true
            }
          }
        ]
      },
      {
        test: /\.jsx$/,
        loader: "babel-loader", // Do not use "use" here
        options: {
          // ...
        }
      }
    ]
  }

鏈式 loaders

與 v1 版本相同，loaders 能夠鏈式調用，上一個 loader 的輸出被做爲輸入傳給下一個 loader。使用 rule.use 配置項，use 能夠設置爲一個 loaders 的列表。在 v1 版本中，loaders 一般被用 ! 連寫。這一寫法在新版中只在使用舊的 module.loaders 時有效。

module: {
-   loaders: {
+   rules: [{
      test: /\.less$/,
-     loader: "style-loader!css-loader!less-loader"
+     use: [
+       "style-loader",
+       "css-loader",
+       "less-loader"
+     ]
    }]
  }

取消了在模塊名中自動添加 -loader 後綴

It is not possible anymore to omit the -loader extension when referencing loaders:

module: {
    rules: [
      {
        use: [
-         "style",
+         "style-loader",
-         "css",
+         "css-loader",
-         "less",
+         "less-loader",
        ]
      }
    ]
  }

你仍然能夠啓用這一舊行爲，方法是經過配置 resolveLoader.moduleExtensions 項，可是咱們不推薦這麼作。

+ resolveLoader: {
+   moduleExtensions: ["-loader"]
+ }

json-loader 再也不須要手動添加

若是沒有爲 JSON 文件配置 loader，webpack 將自動嘗試經過 加載 json-loader JSON 文件。

module: {
    rules: [
-     {
-       test: /\.json/,
-       loader: "json-loader"
-     }
    ]
  }

咱們決定這麼作 以消弭 webpack、 node.js 和 browserify 之間的環境差別。

loader 默認的 resolve 配置是相對於 context 的

在 webpack 1 中，loader 默認配置下 resolve 相對於被匹配的文件。而在 webpack 2 中默認配置的 resolve 相對於 context 配置項。

這解決了一些問題，好比使用 npm link 或引用 context 以外的模塊時致使重複載入。

你能夠再也不須要使用一些變通方案了：

module: {
    rules: [
      {
        // ...
-       loader: require.resolve("my-loader")
+       loader: "my-loader"
      }
    ]
  },
  resolveLoader: {
-   root: path.resolve(__dirname, "node_modules")
  }

取消了 module.preLoaders 以及 module.postLoaders

module: {
-   preLoaders: [
+   rules: [
      {
        test: /\.js$/,
+       enforce: "pre",
        loader: "eslint-loader"
      }
    ]
  }

UglifyJsPlugin sourceMap

UglifyJsPlugin 的 sourceMap 配置項如今默認爲 false 而不是 true。 這意味着若是你在壓縮代碼時啓用了 source map，或者想要讓 uglifyjs 的警告可以對應到正確的代碼行，你須要將 UglifyJsPlugin 的 sourceMap 設爲 true。

devtool: "source-map",
plugins: [
    new UglifyJsPlugin({
+     sourceMap: true
    })
]

UglifyJsPlugin warnings

UglifyJsPlugin 的 compress.warnings 配置項如今默認爲 false 而不是 true。 這意味着若是你想要看到 uglifyjs 的警告信息，你須要將 compress.warnings 設爲 true。

devtool: "source-map",
plugins: [

new UglifyJsPlugin({

• compress: {

• warnings: true

• }

  })

  ]

UglifyJsPlugin 壓縮 loaders

UglifyJsPlugin 再也不壓縮 loaders。在將來很長一段時間裏，須要經過設置 minimize:true 來壓縮 loaders。參考 loader 文檔裏的相關配置項。

loaders 的壓縮模式將在 webpack 3 或更高的版本中被取消。

爲了兼容舊的 loaders，loaders 能夠經過插件來切換到壓縮模式：

plugins: [
+   new webpack.LoaderOptionsPlugin({
+     minimize: true
+   })
]

DedupePlugin 被移除

再也不須要 webpack.optimize.DedupePlugin。請從配置中移除。

BannerPlugin - 破壞性改動

BannerPlugin 不在接受兩個參數而是隻接受單獨的 options 對象。

plugins: [
-    new webpack.BannerPlugin('Banner', {raw: true, entryOnly: true});
+    new webpack.BannerPlugin({banner: 'Banner', raw: true, entryOnly: true});
  ]

OccurrenceOrderPlugin 被默認加載

咱們再也不須要在配置裏指定它：

plugins: [
-   new webpack.optimize.OccurrenceOrderPlugin()
  ]

ExtractTextWebpackPlugin - 大改變

ExtractTextPlugin 1.0.0 不能在 webpack v2 下工做。 你須要明確地安裝 ExtractTextPlugin v2。

npm install --save-dev extract-text-webpack-plugin@beta

這一插件的配置變化主要體如今語法上。

ExtractTextPlugin.extract

module: {
  rules: [
    {
      test: /.css$/,
-      loader: ExtractTextPlugin.extract("style-loader", "css-loader", { publicPath: "/dist" })
+      use: ExtractTextPlugin.extract({
+        fallback: "style-loader",
+        use: "css-loader",
+        publicPath: "/dist"
+      })
    }
  ]
}

new ExtractTextPlugin({options})

plugins: [
-  new ExtractTextPlugin("bundle.css", { allChunks: true, disable: false })
+  new ExtractTextPlugin({
+    filename: "bundle.css",
+    disable: false,
+    allChunks: true
+  })
]

全動態 requires 如今默認會失敗

只有一個表達式的依賴（例如 require(expr)）將建立一個空的 context 而不是一個完整目錄的 context。

若是有上面那樣的代碼，最好把它重構了，由於在 ES2015 模塊下它不能夠用。若是你肯定不會有 ES2015 模塊，你可使用 ContextReplacementPlugin 來提示編譯器進行正確的處理。

在 CLI 和配置中使用自定義參數

若是你以前濫用 CLI 來傳自定義參數到配置中，好比：

webpack --custom-stuff

// webpack.config.js
var customStuff = process.argv.indexOf("--custom-stuff") >= 0;
/* ... */
module.exports = config;

你將會發現新版中再也不容許這麼作。CLI 如今更加嚴格了。

替代地，如今提供了一個接口來傳遞參數給配置。咱們應該採用這種新方式，在將來許多工具將可能依賴它。

webpack --env.customStuff

module.exports = function(env) {
  var customStuff = env.customStuff;
  /* ... */
  return config;
};

詳見 CLI。

require.ensure 以及 AMD require 的異步

如今這些函數老是異步的，而不是當 chunk 已經加載過的時候同步調用它們的 callback。

注意 require.ensure 如今依賴於原生的 Promise。若是在不支持 Promise 的環境裏使用 require.ensure，你須要添加 polyfill。

經過 options 配置 loader

你不能再經過 webpack.config.js 的自定義屬性來配置 loader。只能經過 options 來配置。下面配置的 ts 屬性在 webpack 2 下再也不有效：

module.exports = {
  ...
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'ts-loader'
    }]
  },
  // does not work with webpack 2
  ts: { transpileOnly: false }
}

什麼是 options?

好問題。嚴格來講，有兩種辦法，均可以用來配置 webpack 的 loader。典型的 options 被稱爲 query，是一個能夠被添加到 loader 名以後的字符串。它比較像一個 query string，可是實際上有更強大的能力：

module.exports = {
  ...
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'ts-loader?' + JSON.stringify({ transpileOnly: false })
    }]
  }
}

不過它也能夠分開來，寫成一個單獨的對象，緊跟在 loader 屬性後面：

module.exports = {
  ...
  module: {
    rules: [{
      test: /\.tsx?$/,
      loader: 'ts-loader',
      options:  { transpileOnly: false }
    }]
  }
}

LoaderOptionsPlugin context

有的 loader 須要從配置中讀取一些 context 信息。在將來很長一段時間裏，這將須要經過 loader options 傳入。詳見 loader 文檔的相關選項。

爲了保持對舊 loaders 的兼容，這些信息能夠經過插件傳進來：

plugins: [
+   new webpack.LoaderOptionsPlugin({
+     options: {
+       context: __dirname
+     }
+   })
  ]

debug

在 webpack 1 中 debug 配置項切換 loaders 到 debug 模式。在將來很長一段時間裏，這將須要經過 loader 配置項傳遞。詳見 loader 文檔的相關選項。

loaders 的 debug 模式將在 webpack 3 或後續版本中取消。

爲了保持對舊 loaders 的兼容，loader 能夠經過插件來切換到 debug 模式：

- debug: true,
  plugins: [
+   new webpack.LoaderOptionsPlugin({
+     debug: true
+   })
  ]

ES2015 的代碼分割

在 webpack v1 中，你能使用 require.ensure 做爲方法來懶加載 chunks 到你的應用中：

require.ensure([], function(require) {
  var foo = require("./module");
});

ES2015 模塊加載規範定義了 import() 方法來運行時動態地加載 ES2015 模塊。

webpack 將 import() 做爲分割點並將被請求的模塊放到一個單獨的 chunk 中。

import() 接收模塊名做爲參數，並返回一個 Promise。

function onClick() {
  import("./module").then(module => {
    return module.default;
  }).catch(err => {
    console.log("Chunk loading failed");
  });
}

好消息是：若是加載 chunk 失敗，咱們能夠進行處理，由於如今它基於 Promise。

警告：require.ensure 容許用可選的第三個參數爲 chunk 簡單命名，可是 import API 還未提供這個能力。若是你想要保留這個功能，你能夠繼續使用 require.ensure。

require.ensure([], function(require) {
var foo = require("./module");
}, "custom-chunk-name");
（注意廢棄的 System.import：webpack 對 System.import 的使用不符合新提出的標準，因此它在 v2.1.0-beta.28 版本中被廢棄，轉向支持 import()）

因爲這個建議還在 Stage 3，若是你想要同時使用 import 和 Babel，你須要安裝/添加 dynamic-import 語法插件來繞過解析錯誤。當建議被添加到規範以後，就再也不須要這個語法插件了。

動態表達式

能夠傳遞部分表達式給 import()。這與 CommonJS 對錶達式的處理方式一致（webpack 爲全部可能匹配的文件建立 context）。

import() 爲每個可能的模塊建立獨立的 chunk。

function route(path, query) {
  return import(`./routes/${path}/route`)
    .then(route => new route.Route(query));
}
// 上面代碼爲每一個可能的路由建立獨立的 chunk

混合使用 ES201五、AMD 和 CommonJS

你能夠自由混合使用三種模塊類型（甚至在同一個文件中）。在這個狀況中 webpack 的行爲和 babel 以及 node-eps 一致：

// CommonJS consuming ES2015 Module
var book = require("./book");

book.currentPage;
book.readPage();
book.default === "This is a book";
// ES2015 Module consuming CommonJS
import fs from "fs"; // module.exports map to default
import { readFileSync } from "fs"; // named exports are read from returned object+

typeof fs.readFileSync === "function";
typeof readFileSync === "function";

It is important to note that you will want to tell Babel to not parse these module symbols so webpack can use them. You can do this by setting the following in your .babelrc or babel-loader options.

.babelrc

{
  "presets": [
    ["es2015", { "modules": false }]
  ]
}

Hints:不須要改變什麼，不過也能夠改變。

模板字符串

webpack 如今支持表達式中的模板字符串了。這意味着你能夠在 webpack 構建中使用它們：

- require("./templates/" + name);
+ require(`./templates/${name}`);

配置中使用 Promise

webpack 如今支持在配置文件中返回 Promise 了。這讓你能在配置文件中作異步處理。

webpack.config.js

module.exports = function() {
  return fetchLangs().then(lang => ({
    entry: "...",
    // ...
    plugins: [
      new DefinePlugin({ LANGUAGE: lang })
    ]
  }));
};

高級 loader 匹配

webpack 如今支持對 loader 進行更多方式的匹配。

module: {
  rules: [
    {
      resource: /filename/, // matches "/path/filename.js"
      resourceQuery: /querystring/, // matches "/filename.js?querystring"
      issuer: /filename/, // matches "/path/something.js" if requested from "/path/filename.js"
    }
  ]
}

複合 options

webpack 1 只支持可以 JSON.stringify 的對象做爲配置項。webpack 2 如今支持任意 JS 對象做爲 loader 配置項。

使用複合 options 只有一個附加條件。你須要在 options 對象上添加一個 ident，讓它可以被其餘 loader 引用。

options 對象上有了 ident ，內聯的 loader 就能夠引用這個 options 對象。下面是個例子：

require("some-loader??by-ident!resource")

{
  test: /.../,
  loader: "...",
  options: {
    ident: "by-ident",
    magic: () => return Math.random()
  }
}