From b525c224f928267387923009ad5275622ac3c649 Mon Sep 17 00:00:00 2001 From: Yucohny <79147654+Yucohny@users.noreply.github.com> Date: Tue, 16 Jan 2024 15:24:47 +0800 Subject: [PATCH] docs(cn): improve translations of tree-shaking (#1881) --- src/content/configuration/module.mdx | 2 +- src/content/configuration/optimization.mdx | 24 ++++++------ src/content/guides/tree-shaking.mdx | 10 ++--- src/content/plugins/terser-webpack-plugin.mdx | 38 +++++++------------ 4 files changed, 32 insertions(+), 42 deletions(-) diff --git a/src/content/configuration/module.mdx b/src/content/configuration/module.mdx index 67ce7d1bf0af..1d4f14b1a1a9 100644 --- a/src/content/configuration/module.mdx +++ b/src/content/configuration/module.mdx @@ -986,7 +986,7 @@ module.exports = { `bool` -表明模块的哪一部份包含副作用。详情参阅 [Tree Shaking](/guides/tree-shaking/#mark-the-file-as-side-effect-free)。 +表明模块的哪一部份包含副作用。请参阅 [Tree Shaking](/guides/tree-shaking/#mark-the-file-as-side-effect-free) 以了解更多信息。 ## Rule.test $#ruletest$ diff --git a/src/content/configuration/optimization.mdx b/src/content/configuration/optimization.mdx index 57830898ab98..edbb4c5ad82a 100644 --- a/src/content/configuration/optimization.mdx +++ b/src/content/configuration/optimization.mdx @@ -78,8 +78,8 @@ module.exports = { `boolean` -告知 webpack 去寻找模块图形中的片段，哪些是可以安全地被合并到单一模块中。这取决于 [`optimization.providedExports`](#optimizationprovidedexports) 和 [`optimization.usedExports`](#optimizationusedexports)。 -默认 `optimization.concatenateModules` 在 `生产` [模式](/configuration/mode/) 下被启用，而在其它情况下被禁用。 +告诉 webpack 在模块图中查找可以安全连接到单个模块的片段。此优化首先需要 [`optimization.providedExports`](#optimizationprovidedexports) 与 [`optimization.usedExports`](#optimizationusedexports) 设置为启用。 +默认情况下，`optimization.concatenateModules` 在 `production` [模式](/configuration/mode/) 下启用，而在其它情况下被禁用。 **webpack.config.js** @@ -132,7 +132,7 @@ module.exports = { `boolean = true` -`optimization.innerGraph` 告知 webpack 是否对未使用的导出内容，实施内部图形分析(graph analysis)。 +`optimization.innerGraph` 告诉 webpack 是否对未使用的导出内容实施内部图形分析。 **webpack.config.js** @@ -496,7 +496,7 @@ module.exports = { `boolean = true` `string: 'flag'` -告知 webpack 去辨识 `package.json` 中的 [`副作用`](https://github.com/webpack/webpack/blob/master/examples/side-effects/README.md) 标记或规则，以跳过那些当导出不被使用且被标记不包含副作用的模块。 +告诉 webpack 去辨识 `package.json` 中的 [`sideEffects`](https://github.com/webpack/webpack/blob/master/examples/side-effects/README.md) 标记或规则，以跳过那些当导出不被使用且被标记为不包含副作用的模块。 **package.json** @@ -508,11 +508,11 @@ module.exports = { } ``` -T> 请注意的是 `（副作用）sideEffects` 需要在 npm 模块的 `package.json` 文件中，但并不意味着你需要在你自己的引用那个大模块的项目中的 +T> 请注意，`sideEffects` 应该位于 npm 模块的 `package.json` 文件中，但并不意味着你需要在自己项目中引入大模块的 `package.json` 中将 `sideEffects` 设置成 `false`。 -`optimization.sideEffects` 取决于 [`optimization.providedExports`](#optimizationprovidedexports) 被设置成启用。这个依赖会有构建时间的损耗，但去掉模块会对性能有正面的影响，因为更少的代码被生成。该优化的效果取决于你的代码库， -可以尝试这个特性以获取一些可能的性能优化。 +`optimization.sideEffects` 首先依赖于 [`optimization.providedExports`](#optimizationprovidedexports) 被设置为启用。这个依赖会有构建时间的损耗，但移除模块将生成更少的代码，因此有利于性能的提升。该优化的效果取决于代码库， +可以尝试此特性以获取一些可能的性能优化。 **webpack.config.js** @@ -525,7 +525,7 @@ module.exports = { }; ``` -只使用手动 flag，并且不对源码进行分析： +如果不想要分析源码，那么可以将其指定为 `flag`： ```js module.exports = { @@ -536,9 +536,9 @@ module.exports = { }; ``` -此处的 `'flag'` 值在非生产环境默认使用。 +此处的 `'flag'` 值在非生产环境中默认使用。 -T> 设置为 `optimization.sideEffects` 时，当模块只包含无副作用的语句时，此模块也会被标记为无副作用。 +T> 启用 `optimization.sideEffects` 后，当模块只包含无副作用的语句时，此模块也会被标记为无副作用。 ## optimization.splitChunks $#optimizationsplitchunks$ @@ -550,8 +550,8 @@ T> 设置为 `optimization.sideEffects` 时，当模块只包含无副作用的 `boolean = true` `string: 'global'` -告知 webpack 去决定每个模块使用的导出内容。这取决于 [`optimization.providedExports`](#optimizationprovidedexports) 选项。由 `optimization.usedExports` 收集的信息会被其它优化手段或者代码生成使用，比如未使用的导出内容不会被生成，当所有的使用都适配，导出名称会被处理做单个标记字符。 -在压缩工具中的无用代码清除会受益于该选项，而且能够去除未使用的导出内容。 +告诉 webpack 去决定每个模块的到处内容是否被使用。这首先取决于 [`optimization.providedExports`](#optimizationprovidedexports) 选项是否被启用。由 `optimization.usedExports` 收集的信息会被其它优化手段或者代码生成使用，比如未使用的导出内容不会被生成，当所有的使用都适配，导出名称会被处理做单个标记字符。 +压缩工具执行清除死代码时会受益于该选项，而且能够去除未使用的导出内容。 **webpack.config.js** diff --git a/src/content/guides/tree-shaking.mdx b/src/content/guides/tree-shaking.mdx index 329490bef777..eba3c45fbc94 100644 --- a/src/content/guides/tree-shaking.mdx +++ b/src/content/guides/tree-shaking.mdx @@ -183,7 +183,7 @@ T> 注意，所有导入文件都会受到 tree shaking 的影响。这意味着 **`sideEffects` 更为有效** 是因为它允许跳过整个模块/文件和整个文件子树。 -`usedExports` 依赖于 [terser](https://github.com/terser-js/terser) 检测语句中的副作用。它是一个 JavaScript 任务而且不像 `sideEffects` 一样简单直接。并且由于规范认为副作用需要被评估，因此它不能跳过子树/依赖项。尽管导出函数能正常运行，但 React 的高阶函数在这种情况下会出问题。 +`usedExports` 依赖于 [terser](https://github.com/terser-js/terser) 检测语句中的副作用。它是一个 JavaScript 任务而且不像 `sideEffects` 一样简单直接。并且由于规范认为副作用需要被评估，因此它不能跳过子树/依赖项。尽管导出函数能正常运行，但 React 的高阶组件在这种情况下会出问题。 让我们来看一个例子： @@ -244,9 +244,9 @@ export { }; ``` -当 `Button` 没有被使用时可以有效地删除 `export { Button$1 };`，这样就只留下了所有其余的代码。所以问题是：“这段代码是否有任何副作用，或者可以安全地删除吗？”很难说，特别是因为这行代码 `withAppProvider()(Button)`。`withAppProvider` 被调用，并且返回值也被调用。在调用 `merge` 或 `hoistStatics` 时有任何副作用吗？在向 `WithProvider.contextTypes`（Setter）赋值或读取 `WrappedComponent.contextTypes`（Getter）会有任何副作用吗？ +当 `Button` 没有被使用时，删除 `export { Button$1 };` 并保留其余所有代码会让代码变得更加高效。所以问题是：“这段代码是否有任何副作用，是否可以安全删除？”这很难说，尤其是因为这行代码 `withAppProvider()(Button)`。在这行代码中，`withAppProvider` 被调用了，并且其返回值（译注：请注意，`withAppProvider` 的返回值是一个函数）也被调用了。那么当执行 `withAppProvider` 及其返回值时，调用 `merge` 与 `hoistStatics` 会有任何副作用吗？读取 `WrappedComponent.contextTypes`（Getter）或向 `WithProvider.contextTypes`（Setter）赋值时会有任何副作用吗？ -实际上，terser 尝试去解决这些问题，但在许多情况下它仍然不确定。但这并不意味着 terser 会由于无法解决这些问题而运作得不好。根本原因在于像 JavaScript 这种动态语言中很难可靠确定这一点。 +实际上，`usedExports` 依赖的 terser 就尝试去解决这些问题，但在许多情况下它仍然不确定函数的调用是否有副作用。但这并不意味着 terser 会由于无法解决这些问题而运作得不好。根本原因在于像 JavaScript 这类动态语言中很难可靠确定这一点。 但我们可以通过 `/*#__PURE__*/` 注释来帮助 terser。这个注释的作用是标记此语句没有副作用。这样一个简单的改变就能够 tree-shake 下面的代码了： @@ -254,11 +254,11 @@ export { var Button$1 = /*#__PURE__*/ withAppProvider()(Button); ``` -这会使得这段代码被过滤，但仍然会有一些引入的问题，需要对其进行评估，因为它们产生了副作用。 +这将允许删除这段代码。但是除此之外，引入的内容可能仍然存在副作用的问题，因此需要对其进入评估。 为了解决这个问题，我们需要在 `package.json` 中添加 [`"sideEffects"`](/guides/tree-shaking/#mark-the-file-as-side-effect-free) 属性。 -它类似于 `/*#__PURE__*/` 但是作用于模块的层面，而不是代码语句的层面。`"sideEffects"` 属性的意思是：“如果被标记为无副作用的模块没有被直接导出使用，打包工具会跳过进行模块的副作用分析评估”。 +它与 `/*#__PURE__*/` 类似，但是作用于模块层面，而非代码语句的层面。`"sideEffects"` 属性的意思是：“如果没有使用被标记为无副作用的模块的直接导出，那么捆绑器会跳过对此模块的副作用评估”。 考虑 `Shopify Polaris` 的例子，原有的模块如下： diff --git a/src/content/plugins/terser-webpack-plugin.mdx b/src/content/plugins/terser-webpack-plugin.mdx index c9b4dd9e3fc5..a316786ed4e7 100644 --- a/src/content/plugins/terser-webpack-plugin.mdx +++ b/src/content/plugins/terser-webpack-plugin.mdx @@ -7,21 +7,13 @@ repo: https://github.com/webpack-contrib/terser-webpack-plugin translators: - 92hackers - QC-L + - Yucohny --- -
- - - -
+免责声明：TerserWebpackPlugin 是由社区成员维护的第三方包，它可能没有与 webpack 相同的支持、安全策略或许可证，并且它不是由 webpack 维护的。 [![npm][npm]][npm-url] [![node][node]][node-url] -[![deps][deps]][deps-url] [![tests][tests]][tests-url] [![cover][cover]][cover-url] [![chat][chat]][chat-url] @@ -33,13 +25,13 @@ translators: webpack v5 开箱即带有最新版本的 `terser-webpack-plugin`。如果你使用的是 webpack v5 或更高版本，同时希望自定义配置，那么仍需要安装 `terser-webpack-plugin`。如果使用 webpack v4，则必须安装 `terser-webpack-plugin` v4 的版本。 -首先，你需要安装 `terser-webpack-plugin`： +首先需要安装 `terser-webpack-plugin`： ```console npm install terser-webpack-plugin --save-dev ``` -然后将插件添加到你的 `webpack` 配置文件中。例如： +然后将插件添加到 `webpack` 配置文件中，例如： **webpack.config.js** @@ -56,28 +48,26 @@ module.exports = { 接下来，按照你习惯的方式运行 `webpack`。 -## 关于 source maps 说明 $#note-about-source-maps$ +## 关于 source map 的说明 $#note-about-source-maps$ **只对 [`devtool`](/configuration/devtool/) 选项的 `source-map`，`inline-source-map`，`hidden-source-map` 和 `nosources-source-map` 有效**。 为何如此？ -- `eval` 会包裹 modules，通过 `eval("string")`，而 minimizer 不会处理字符串。 -- `cheap` 不存在列信息，minimizer 只产生单行，只会留下一个映射。 +- `eval` 通过 `eval("string")` 包裹模块而压缩工具不会处理字符串。 +- `cheap` 不存在列信息而压缩工具输出的文件为单行文件，只会留下一个映射。 使用支持的 `devtool` 值可以生成 source map。 ## 选项 $#options$ -| 选项名 | 类型 | 默认值 | 描述 | -| :---------------------------------------: | :-----------------------------------------------------------------------------: | :----------------------------------------------------------: | :------------------------------------------------------------------------- | -| **[`test`](#test)** | `String\|RegExp\|Array` | `/\.m?js(\?.*)?$/i` | 用来匹配需要压缩的文件。 | -| **[`include`](#include)** | `String\|RegExp\|Array` | `undefined` | 匹配参与压缩的文件。 | -| **[`exclude`](#exclude)** | `String\|RegExp\|Array` | `undefined` | 匹配不需要压缩的文件。 | -| **[`parallel`](#parallel)** | `Boolean\|Number` | `true` | 使用多进程并发运行以提高构建速度。 | -| **[`minify`](#minify)** | `Function` | `TerserPlugin.terserMinify` | 允许你自定义压缩函数。 | -| **[`terserOptions`](#terseroptions)** | `Object` | [`default`](https://github.com/terser/terser#minify-options) | Terser 的 [minify 选项](https://github.com/terser/terser#minify-options)。 | -| **[`extractComments`](#extractcomments)** | `Boolean\|String\|RegExp\|Function<(node, comment) -> Boolean\|Object>\|Object` | `true` | 注释是否需要提取到一个单独的文件中。 | +- **[`test`](#test)** +- **[`include`](#include)** +- **[`exclude`](#exclude)** +- **[`parallel`](#parallel)** +- **[`minify`](#minify)** +- **[`terserOptions`](#terseroptions)** +- **[`extractComments`](#extractcomments)** ### `test` $#test$