Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(cn): improve translations of tree-shaking #1881

Merged
merged 5 commits into from
Jan 16, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading