diff --git a/src/content/migrate/3.md b/src/content/migrate/3.md index 05152b2f7bd5..29eedf589abd 100644 --- a/src/content/migrate/3.md +++ b/src/content/migrate/3.md @@ -1,5 +1,5 @@ --- -title: To v2 or v3 from v1 +title: 从 v1 升级到 v2 或 v3 sort: 3 contributors: - sokra @@ -18,14 +18,14 @@ contributors: - byzyk --- -The following sections describe the major changes from webpack 1 to 2. +以下各节描述从 webpack 1 到 webpack 2 的重大变化。 -T> Note that there were far fewer changes between 2 and 3, so that migration shouldn't be too bad. If you are running into issues, please see [the changelog](https://github.com/webpack/webpack/releases) for details. +T> 注意:webpack 从 1 到 2 的变化,比从 2 到 3 要少很多,所以版本迁移起来难度应该不大。如果你遇到了问题,请查看[更新日志](https://github.com/webpack/webpack/releases) 以了解更多细节。 ## `resolve.root`, `resolve.fallback`, `resolve.modulesDirectories` -These options were replaced by a single option `resolve.modules`. See [resolving](/configuration/resolve) for more usage. +这些选项被一个单独的选项 `resolve.modules` 取代。更多用法请查看 [resolving](/configuration/resolve) 。 ``` diff resolve: { @@ -40,19 +40,19 @@ These options were replaced by a single option `resolve.modules`. See [resolving ## `resolve.extensions` -This option no longer requires passing an empty string. This behavior was moved to `resolve.enforceExtension`. See [resolving](/configuration/resolve) for more usage. +此选项不再需要传一个空字符串。此行为被迁移到 `resolve.enforceExtension` 。更多用法请查看 [解析](/configuration/resolve) 。 ## `resolve.*` -Several APIs were changed here. Not listed in detail as it's not commonly used. See [resolving](/configuration/resolve) for details. +这里更改了几个 API 。由于不常用,不在这里详细列出。更多用法请查看 [解析](/configuration/resolve) 。 -## `module.loaders` is now `module.rules` +## `module.loaders` 升级为 `module.rules` -The old loader configuration was superseded by a more powerful rules system, which allows configuration of loaders and more. -For compatibility reasons, the old `module.loaders` syntax is still valid and the old names are parsed. -The new naming conventions are easier to understand and are a good reason to upgrade the configuration to using `module.rules`. +旧的 loader 配置被更强大的 rules 系统取代,后者允许配置 loader 以及其他更多选项。 +为了兼容旧版,`module.loaders` 语法仍然有效,旧的属性名依然可以被解析。 +新的命名约定更易于理解,并且是升级配置使用 `module.rules` 的好理由。 ``` diff module: { @@ -77,7 +77,7 @@ The new naming conventions are easier to understand and are a good reason to upg }, { test: /\.jsx$/, - loader: "babel-loader", // Do not use "use" here + loader: "babel-loader", // 在这里不要使用 "use" options: { // ... } @@ -87,11 +87,11 @@ The new naming conventions are easier to understand and are a good reason to upg ``` -## Chaining loaders +## 链式 loaders -Like in webpack 1, loaders can be chained to pass results from loader to loader. Using the [rule.use](/configuration/module/#ruleuse) - configuration option, `use` can be set to an array of loaders. -In webpack 1, loaders were commonly chained with `!`. This style is only supported using the legacy option `module.loaders`. +就像在 webpack 1 中,loader 可以链式调用,上一个 loader 的输出被作为输入传给下一个 loader。 +使用 [rule.use](/configuration/module/#ruleuse) 配置选项,`use` 可以设置为一个 loader 数组。 +在 webpack 1 中,loader 通常被用 `!` 连写。这一写法在 webpack 2 中只在使用旧的选项 `module.loaders` 时才有效。 ``` diff module: { @@ -109,9 +109,9 @@ In webpack 1, loaders were commonly chained with `!`. This style is only support ``` -## Automatic `-loader` module name extension removed +## 已移除 `-loader` 模块名称自动扩展 -It is not possible anymore to omit the `-loader` extension when referencing loaders: +在引用 loader 时,不能再省略 `-loader` 后缀了: ``` diff module: { @@ -130,7 +130,7 @@ It is not possible anymore to omit the `-loader` extension when referencing load } ``` -You can still opt-in to the old behavior with the `resolveLoader.moduleExtensions` configuration option, but this is not recommended. +你仍然可以通过配置 `resolveLoader.moduleExtensions` 配置选项,启用这一旧有行为,但是我们不推荐这么做。 ``` diff + resolveLoader: { @@ -138,13 +138,13 @@ You can still opt-in to the old behavior with the `resolveLoader.moduleExtension + } ``` -See [#2986](https://github.com/webpack/webpack/issues/2986) for the reason behind this change. +了解这一改变背后的原因,请查看 [#2986](https://github.com/webpack/webpack/issues/2986) 。 -## `json-loader` is not required anymore +## `json-loader` 不再需要手动添加 -When no loader has been configured for a JSON file, webpack will automatically try to load the JSON -file with the [`json-loader`](https://github.com/webpack-contrib/json-loader). +如果没有为 JSON 文件配置 loader,webpack 将自动尝试通过 [`json-loader`] +(https://github.com/webpack-contrib/json-loader) 加载 JSON 文件。 ``` diff module: { @@ -157,17 +157,17 @@ file with the [`json-loader`](https://github.com/webpack-contrib/json-loader). } ``` -[We decided to do this](https://github.com/webpack/webpack/issues/3363) in order to iron out environment differences - between webpack, node.js and browserify. +[我们决定这样做](https://github.com/webpack/webpack/issues/3363) +是为了消除 webpack、 node.js 和 browserify 之间的环境差异。 -## Loaders in configuration resolve relative to context +## 配置中的 loader 默认相对于 context 进行解析 -In __webpack 1__, configured loaders resolve relative to the matched file. However, in __webpack 2__, configured loaders resolve relative to the `context` option. +在 __webpack 1__ 中,默认配置下 loader 解析相对于被匹配的文件。然而,在 __webpack 2__ 中,默认配置下 loader 解析相对于 `context` 选项。 -This solves some problems with duplicate modules caused by loaders when using `npm link` or referencing modules outside of the `context`. +这解决了「在使用 `npm link` 或引用 `context` 上下文目录之外的模块时,loader 所导致的模块重复载入」的问题。 -You may remove some hacks to work around this: +你可以移除掉那些为解决此问题的 hack 方案了: ``` diff module: { @@ -185,7 +185,7 @@ You may remove some hacks to work around this: ``` -## `module.preLoaders` and `module.postLoaders` were removed: +## 移除了 `module.preLoaders` 和 `module.postLoaders` : ``` diff module: { @@ -203,7 +203,7 @@ You may remove some hacks to work around this: ## `UglifyJsPlugin` sourceMap -The `sourceMap` option of the `UglifyJsPlugin` now defaults to `false` instead of `true`. This means that if you are using source maps for minimized code or want correct line numbers for uglifyjs warnings, you need to set `sourceMap: true` for `UglifyJsPlugin`. + `UglifyJsPlugin` 的 `sourceMap` 选项现在默认为 `false` 而不是 `true`。这意味着如果你在压缩代码时启用了 `source map`,或者想要让 `uglifyjs` 的警告能够对应到正确的代码行,你需要将 `UglifyJsPlugin` 的 `sourceMap` 设为 `true` 。 ``` diff devtool: "source-map", @@ -217,8 +217,8 @@ The `sourceMap` option of the `UglifyJsPlugin` now defaults to `false` instead o ## `UglifyJsPlugin` warnings -The `compress.warnings` option of the `UglifyJsPlugin` now defaults to `false` instead of `true`. -This means that if you want to see uglifyjs warnings, you need to set `compress.warnings` to `true`. + `UglifyJsPlugin` 的 `compress.warnings` 选项现在默认为 `false` 而不是 `true` 。 这意味着如果你想要看到 `uglifyjs` 的警告信息,你需要将 `compress.warnings` 设为 `true。` + ``` diff devtool: "source-map", @@ -232,13 +232,13 @@ This means that if you want to see uglifyjs warnings, you need to set `compress. ``` -## `UglifyJsPlugin` minimize loaders +## `UglifyJsPlugin` 压缩优化 loaders -`UglifyJsPlugin` no longer switches loaders into minimize mode. The `minimize: true` setting needs to be passed via loader options in the long-term. See loader documentation for relevant options. +`UglifyJsPlugin` 不再压缩 loaders。在未来很长一段时间里,需要通过设置 `minimize:true` 来压缩 loaders。参考 loader 文档里的相关选项。 -The minimize mode for loaders will be removed in webpack 3 or later. +loaders 的压缩模式将在 webpack 3 或后续版本中取消。 -To keep compatibility with old loaders, loaders can be switched to minimize mode via plugin: +为了兼容旧的 loaders,loaders 可以通过插件来切换到压缩模式: ``` diff plugins: [ @@ -249,14 +249,14 @@ To keep compatibility with old loaders, loaders can be switched to minimize mode ``` -## `DedupePlugin` has been removed +## 移除 `DedupePlugin` -`webpack.optimize.DedupePlugin` isn't needed anymore. Remove it from your configuration. +不再需要 `webpack.optimize.DedupePlugin`。请从配置中移除。 -## `BannerPlugin` - breaking change +## `BannerPlugin` - 破坏性改动 -`BannerPlugin` no longer accepts two parameters, but a single options object. +`BannerPlugin` 不再接受两个参数,而是只接受单独的 options 对象。 ``` diff plugins: [ @@ -266,10 +266,10 @@ To keep compatibility with old loaders, loaders can be switched to minimize mode ``` -## `OccurrenceOrderPlugin` is now on by default +## 默认加载 `OccurrenceOrderPlugin` -The `OccurrenceOrderPlugin` is now enabled by default and has been renamed (`OccurenceOrderPlugin` in webpack 1). -Thus make sure to remove the plugin from your configuration: + `OccurrenceOrderPlugin` 现在默认启用,并已重命名(在webpack 1 中为 `OccurenceOrderPlugin`) 。 + 因此,请确保从你的配置中删除该插件: ``` diff plugins: [ @@ -281,13 +281,13 @@ Thus make sure to remove the plugin from your configuration: ``` -## `ExtractTextWebpackPlugin` - breaking change +## `ExtractTextWebpackPlugin` - 破坏性改动 -[ExtractTextPlugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) requires version 2 to work with webpack 2. +[ExtractTextPlugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) 需要使用版本 2,才能在 webpack 2 下正常运行 。 `npm install --save-dev extract-text-webpack-plugin` -The configuration changes for this plugin are mainly syntactical. +这一插件的配置变化主要体现在语法上。 ### `ExtractTextPlugin.extract` @@ -322,17 +322,17 @@ plugins: [ ``` -## Full dynamic requires now fail by default +## 全动态 require 现在默认会失败 -A dependency with only an expression (i. e. `require(expr)`) will now create an empty context instead of the context of the complete directory. +只有一个表达式的依赖(例如 `require(expr)`)将创建一个空的 context 而不是一个完整目录的 context。 -Code like this should be refactored as it won't work with ES2015 modules. If this is not possible you can use the `ContextReplacementPlugin` to hint the compiler towards the correct resolving. +这样的代码应该进行重构,因为它不能与 ES2015 模块一起使用。如果你确定不会有 ES2015 模块,你可以使用 `ContextReplacementPlugin` 来指示 compiler 进行正确的解析。 ?> Link to an article about dynamic dependencies. -### Using custom arguments in CLI and configuration +### 在 CLI 和配置中使用自定义参数 -If you abused the CLI to pass custom arguments to the configuration like so: +如果你之前滥用 CLI 来传自定义参数到配置中,比如: `webpack --custom-stuff` @@ -343,9 +343,9 @@ var customStuff = process.argv.indexOf('--custom-stuff') >= 0; module.exports = config; ``` -You may notice that this is no longer allowed. The CLI is more strict now. +你将会发现新版中不再允许这么做。CLI 现在更加严格了。 -Instead there is an interface for passing arguments to the configuration. This should be used instead. Future tools may rely on this. +替代地,现在提供了一个接口来传递参数给配置。我们应该采用这种新方式,在未来许多工具将可能依赖于此。 `webpack --env.customStuff` @@ -357,19 +357,19 @@ module.exports = function(env) { }; ``` -See [CLI](/api/cli). +详见 [CLI](/api/cli) 。 -## `require.ensure` and AMD `require` are asynchronous +## `require.ensure` 以及 AMD `require` 将采用异步式调用 -These functions are now always asynchronous instead of calling their callback synchronously if the chunk is already loaded. +现在这些函数总是异步的,而不是当 chunk 已经加载完成的时候同步调用它们的回调函数 (callback) 。 -__`require.ensure` now depends upon native `Promise`s. If using `require.ensure` in an environment that lacks them then you will need a polyfill.__ +__`require.ensure` 现在依赖原生的 `Promise`s 。如果不支持 Promise 的环境中使用 `require.ensure` ,你需要添加 polyfill.__ 。 -## Loader configuration is through `options` +## 通过 `options` 中配置 loader -You can _no longer_ configure a loader with a custom property in the `webpack.config.js`. It must be done through the `options`. The following configuration with the `ts` property is no longer valid with webpack 2: +你_不能再_通过 `webpack.config.js` 的自定义属性来配置 loader 。只能通过 `options` 来配置。下面配置的 `ts` 属性在 webpack 2 下不再有效: ```js module.exports = { @@ -380,15 +380,15 @@ module.exports = { loader: 'ts-loader' }] }, - // does not work with webpack 2 + // 在 webpack 2 中无效 ts: { transpileOnly: false } }; ``` -### What are `options`? +### 什么是 `options` ? -Good question. Well, strictly speaking it's 2 possible things; both ways to configure a webpack loader. Classically `options` was called `query` and was a string which could be appended to the name of the loader. Much like a query string but actually with [greater powers](https://github.com/webpack/loader-utils#parsequery): +好问题。严格来说,有两种办法,都可以用来配置 webpack 的 loader 。典型的 `options` 被称为 `query`,是一个可以被添加到 loader 名之后的字符串。它比较像一个查询字符串(query string),但是实际上有[更强大的能力](https://github.com/webpack/loader-utils#parsequery): ```js module.exports = { @@ -402,7 +402,7 @@ module.exports = { }; ``` -But it can also be a separately specified object that's supplied alongside a loader: +不过它也可以分开来,写成一个单独的对象,紧跟在 loader 属性后面: ```js module.exports = { @@ -420,9 +420,9 @@ module.exports = { ## `LoaderOptionsPlugin` context -Some loaders need context information and read them from the configuration. This needs to be passed via loader options in the long-term. See loader documentation for relevant options. +有的 loader 需要从配置中读取一些 context 信息。在未来很长一段时间里,这将需要通过 loader options 传入。详见 loader 文档的相关选项。 -To keep compatibility with old loaders, this information can be passed via plugin: +为了保持对旧 loaders 的兼容,这些信息可以通过插件传进来: ``` diff plugins: [ @@ -437,11 +437,11 @@ To keep compatibility with old loaders, this information can be passed via plugi ## `debug` -The `debug` option switched loaders to debug mode in webpack 1. This needs to be passed via loader options in long-term. See loader documentation for relevant options. +在 webpack 1 中 `debug` 选项可以将 loader 切换到调试模式 (debug mode) 。在未来很长一段时间里,这将需要通过 loader 选项传递。详见 loader 文档的相关选项。 -The debug mode for loaders will be removed in webpack 3 or later. +loaders 的调试模式将在 webpack 3 或后续版本中取消。 -To keep compatibility with old loaders, loaders can be switched to debug mode via a plugin: +为了保持对旧 loaders 的兼容,loader 可以通过插件来切换到调试模式: ``` diff - debug: true, @@ -453,9 +453,9 @@ To keep compatibility with old loaders, loaders can be switched to debug mode vi ``` -## Code Splitting with ES2015 +## ES2015 的代码分割 -In webpack 1, you could use [`require.ensure()`](/api/module-methods/#requireensure) as a method to lazily-load chunks for your application: +在 webpack 1 中,可以使用 [`require.ensure()`](/api/module-methods/#requireensure) 作为实现应用程序的懒加载 chunks 的一种方法: ```javascript require.ensure([], function(require) { @@ -463,7 +463,7 @@ require.ensure([], function(require) { }); ``` -The ES2015 Loader spec defines [`import()`](/api/module-methods/#import-1) as method to load ES2015 Modules dynamically on runtime. webpack treats `import()` as a split-point and puts the requested module in a separate chunk. `import()` takes the module name as argument and returns a Promise. +ES2015 模块加载规范定义了 [`import()`](/api/module-methods/#import-1) 方法,可以在运行时 (runtime) 动态地加载 ES2015 模块。webpack 将 `import()` 作为分割点 (split-point) 并将所要请求的模块 (requested module) 放置到一个单独的 chunk 中。`import()` 接收模块名作为参数,并返回一个 Promise 。 ```js function onClick() { @@ -475,30 +475,30 @@ function onClick() { } ``` -Good news: Failure to load a chunk can now be handled because they are `Promise` based. +好消息是:如果加载 chunk 失败,我们现在可以进行处理,因为现在它基于 `Promise`。 -## Dynamic expressions +## 动态表达式 -It's possible to pass a partial expression to `import()`. This is handled similar to expressions in CommonJS (webpack creates a [context](/plugins/context-replacement-plugin/) with all possible files). +可以传递部分表达式给 `import()` 。这与 CommonJS 对表达式的处理方式一致(webpack 为所有可能匹配的文件创建 context](/plugins/context-replacement-plugin/)) )。 -`import()` creates a separate chunk for each possible module. +`import()` 为每一个可能的模块创建独立的 chunk。 ```js function route(path, query) { return import(`./routes/${path}/route`) .then(route => new route.Route(query)); } -// This creates a separate chunk for each possible route +// 上面代码为每个可能的路由创建独立的 chunk ``` -## Mixing ES2015 with AMD and CommonJS +## 混合使用 ES2015、AMD 和 CommonJS -As for AMD and CommonJS you can freely mix all three module types (even within the same file). webpack behaves similar to babel and node-eps in this case: +你可以自由混合使用三种模块类型(甚至在同一个文件中)。在这个情况中 webpack 的行为和 babel 以及 node-eps 一致: ```javascript -// CommonJS consuming ES2015 Module +// CommonJS 调用 ES2015 模块 var book = require('./book'); book.currentPage; @@ -507,15 +507,15 @@ book.default === 'This is a book'; ``` ```javascript -// ES2015 Module consuming CommonJS -import fs from 'fs'; // module.exports map to default -import { readFileSync } from 'fs'; // named exports are read from returned object+ +// ES2015 模块调用 CommonJS +import fs from 'fs'; // module.exports 映射到 default +import { readFileSync } from 'fs'; // 从返回对象(returned object+)中读取命名的导出方法(named exports) 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. +值得注意的是,你需要让 Babel 不解析这些模块符号,从而让 webpack 可以使用它们。你可以通过设置如下配置到 .babelrc 或 babel-loader 来实现这一点。 __.babelrc__ @@ -530,11 +530,11 @@ __.babelrc__ ## Hints -No need to change something, but opportunities +不需要改变什么,但有机会改变。 -### Template strings +### 模版字符串 -webpack now supports template strings in expressions. This means you can start using them in webpack constructs: +webpack 现在支持表达式中的模板字符串了。这意味着你可以在 webpack 构建中使用它们: ``` diff - require("./templates/" + name); @@ -542,9 +542,9 @@ webpack now supports template strings in expressions. This means you can start u ``` -### Configuration Promise +### 配置中使用 Promise -webpack now supports returning a `Promise` from the configuration file. This allows async processing in your configuration file. +webpack 现在支持在配置文件中返回 `Promise` 了。这让你能在配置文件中做异步处理。 __webpack.config.js__ @@ -561,9 +561,9 @@ module.exports = function() { ``` -### Advanced loader matching +### 高级 loader 匹配 -webpack now supports more things to match on for loaders. +webpack 现在支持对 loader 进行更多方式的匹配。 ```js module.exports = { @@ -571,9 +571,9 @@ module.exports = { module: { rules: [ { - resource: /filename/, // matches "/path/filename.js" - resourceQuery: /^\?querystring$/, // matches "?querystring" - issuer: /filename/, // matches "/path/something.js" if requested from "/path/filename.js" + resource: /filename/, // 匹配 "/path/filename.js" + resourceQuery: /^\?querystring$/, // 匹配 "?querystring" + issuer: /filename/, // 如果请求 "/path/filename.js" 则匹配 "/path/something.js" } ] } @@ -581,32 +581,32 @@ module.exports = { ``` -### More CLI options +### 更多的 CLI 参数项 -There are some new CLI options for you to use: +你可以使用一些新的 CLI 参数项: -`--define process.env.NODE_ENV="production"` See [`DefinePlugin`](/plugins/define-plugin/). +`--define process.env.NODE_ENV="production"` 见 [`DefinePlugin`](/plugins/define-plugin/) 。 -`--display-depth` displays the distance to the entry point for each module. +`--display-depth` 显示每个模块到入口的距离。 -`--display-used-exports` display info about which exports are used in a module. +`--display-used-exports` 显示一个模块中被使用的 exports 信息。 -`--display-max-modules` sets the number for modules displayed in the output (defaults to 15). +`--display-max-modules` 设置输出时显示的模块数量(默认是 15)。 -`-p` also defines `process.env.NODE_ENV` to `"production"` now. +`-p` 能够定义`process.env.NODE_ENV` 为 `"production"` 。 -## Loader changes +## Loader 变更 -Changes only relevant for loader authors. +以下变更仅影响 loader 的开发者。 ### Cacheable -Loaders are now cacheable by default. Loaders must opt-out if they are not cacheable. +Loaders 现在默认可被缓存。Loaders 如果不想被缓存,需要选择不被缓存。 ``` diff - // Cacheable loader + // 缓存 loader module.exports = function(source) { - this.cacheable(); return source; @@ -614,7 +614,7 @@ Loaders are now cacheable by default. Loaders must opt-out if they are not cache ``` ``` diff - // Not cacheable loader + // 不缓存 loader module.exports = function(source) { + this.cacheable(false); return source; @@ -622,13 +622,13 @@ Loaders are now cacheable by default. Loaders must opt-out if they are not cache ``` -### Complex options +### 复杂 options -__webpack 1__ only supports `JSON.stringify`-able options for loaders. +__webpack 1__ 只支持能够「可 `JSON.stringify` 的对象」作为 loader 的 options。 -__webpack 2__ now supports any JS object as loader options. +__webpack 2__ 现在支持任意 JS 对象作为 loader 的 options。 -Before webpack [2.2.1](https://github.com/webpack/webpack/releases/tag/v2.2.1) (i.e. from 2.0.0 through 2.2.0), using complex options required using `ident` for the `options` object to allow its reference from other loaders. __This was removed in 2.2.1__ and thus current migrations do not require any use of the `ident` key. +webpack [2.2.1](https://github.com/webpack/webpack/releases/tag/v2.2.1) 之前(即从 2.0.0 到 2.2.0),使用复合 `options` ,需要在 `options` 对象上添加 `ident`,允许它能够被其他 loader 引用。这 __在 2.2.1 中被删除__ ,因此目前的迁移不再需要使用 `ident` 键。 ```diff {