Skip to content

Commit

Permalink
docs(cn): improve translations of tree-shaking (#1881)
Browse files Browse the repository at this point in the history
  • Loading branch information
Yucohny authored Jan 16, 2024
1 parent 8f8b0b2 commit b525c22
Show file tree
Hide file tree
Showing 4 changed files with 32 additions and 42 deletions.
2 changes: 1 addition & 1 deletion src/content/configuration/module.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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$

Expand Down
24 changes: 12 additions & 12 deletions src/content/configuration/optimization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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**

Expand Down Expand Up @@ -132,7 +132,7 @@ module.exports = {

`boolean = true`

`optimization.innerGraph` 告知 webpack 是否对未使用的导出内容,实施内部图形分析(graph analysis)
`optimization.innerGraph` 告诉 webpack 是否对未使用的导出内容实施内部图形分析

**webpack.config.js**

Expand Down Expand Up @@ -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**

Expand All @@ -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**

Expand All @@ -525,7 +525,7 @@ module.exports = {
};
```

只使用手动 flag,并且不对源码进行分析
如果不想要分析源码,那么可以将其指定为 `flag`

```js
module.exports = {
Expand All @@ -536,9 +536,9 @@ module.exports = {
};
```

此处的 `'flag'` 值在非生产环境默认使用
此处的 `'flag'` 值在非生产环境中默认使用

T> 设置为 `optimization.sideEffects` ,当模块只包含无副作用的语句时,此模块也会被标记为无副作用。
T> 启用 `optimization.sideEffects` ,当模块只包含无副作用的语句时,此模块也会被标记为无副作用。

## optimization.splitChunks $#optimizationsplitchunks$

Expand All @@ -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**

Expand Down
10 changes: 5 additions & 5 deletions src/content/guides/tree-shaking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 的高阶组件在这种情况下会出问题

让我们来看一个例子:

Expand Down Expand Up @@ -244,21 +244,21 @@ 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 下面的代码了:

```javascript
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` 的例子,原有的模块如下:

Expand Down
38 changes: 14 additions & 24 deletions src/content/plugins/terser-webpack-plugin.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -7,21 +7,13 @@ repo: https://github.com/webpack-contrib/terser-webpack-plugin
translators:
- 92hackers
- QC-L
- Yucohny
---

<div align="center">
<a href="https://github.com/webpack/webpack">
<img
width="200"
height="200"
src="https://webpack.js.org/assets/icon-square-big.svg"
/>
</a>
</div>
免责声明: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]
Expand All @@ -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**

Expand All @@ -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<String\|RegExp>` | `/\.m?js(\?.*)?$/i` | 用来匹配需要压缩的文件。 |
| **[`include`](#include)** | `String\|RegExp\|Array<String\|RegExp>` | `undefined` | 匹配参与压缩的文件。 |
| **[`exclude`](#exclude)** | `String\|RegExp\|Array<String\|RegExp>` | `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$

Expand Down

0 comments on commit b525c22

Please sign in to comment.