docs(builder): add more guides for bundle analyzer (#3758)

Co-authored-by: yangxingyuan <[email protected]>

Author: chenjiahan

packages/document/builder-doc/docs/en/config/performance/bundleAnalyze.md

@@ -1,30 +1,75 @@
 - **Type:** `Object | undefined`
 
-You have two ways to enable `webpack-bundle-analyzer` to analyze the size of output files:
+Used to enable the [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) plugin to analyze the size of the output.
 
-- Add environment variable `BUNDLE_ANALYZE=true`.
-- Add `performance.bundleAnalyze` config.
-
-By default, `webpack-bundle-analyzer` is not enabled. When enabled, its configuration is as follows:
+By default, Builder does not enable `webpack-bundle-analyzer`. When this feature is enabled, the default configuration is as follows:
 
 ```js
-{
+const defaultConfig = {
   analyzerMode: 'static',
   openAnalyzer: false,
-  // `target` is the compilation target, such as `web`, `node`, etc.
+  // target is the compilation target, such as `web`, `node`, etc.
   reportFilename: `report-${target}.html`,
-}
+};
+```
+
+### Enable Bundle Analyze
+
+You have two ways to enable `webpack-bundle-analyzer` to analyze the size of the output files:
+
+- Add the environment variable `BUNDLE_ANALYZE=true`, for example:
+
+```bash
+BUNDLE_ANALYZE=true pnpm build
+```
+
+- Configure `performance.bundleAnalyze` to enable it permanently:
+
+```js
+export default {
+  performance: {
+    bundleAnalyze: {},
+  },
+};
 ```
 
-You can override the default config through `performance.bundleAnalyze`, for example:
+After enabling it, Builder will generate an HTML file that analyzes the size of the output files, and print the following log in the Terminal:
+
+```bash
+Webpack Bundle Analyzer saved report to /Project/my-project/dist/report-web.html
+```
+
+You can manually open the file in the browser and view the detail of the bundle size. When an area is larger, it indicates that its corresponding bundle size is larger.
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png)
+
+### Override Default Configuration
+
+You can override the default configuration through `performance.bundleAnalyze`, such as enabling the server mode:
 
 ```js
 export default {
   performance: {
-    bundleAnalyze: {
-      analyzerMode: 'server',
-      openAnalyzer: true,
-    },
+    bundleAnalyze: process.env.BUNDLE_ANALYZE
+      ? {
+          analyzerMode: 'server',
+          openAnalyzer: true,
+        }
+      : {},
   },
 };
 ```
+
+### Size Types
+
+In the `webpack-bundle-analyzer` panel, you can control size types in the upper left corner (default is `Parsed`):
+
+- `Stat`: The size obtained from the `stats` object of the bundler, which reflects the size of the code before minification.
+- `Parsed`: The size of the file on the disk, which reflects the size of the code after minification.
+- `Gzipped`: The file size requested in the browser reflects the size of the code after minification and gzip.
+
+### Notes
+
+1. Enabling the server mode will cause the `build` process to not exit normally.
+2. Enabling `bundleAnalyzer` will reduce build speed. Therefore, this configuration should not be enabled during daily development, and it is recommended to enable it on demand through the `BUNDLE_ANALYZE` environment variable.
+3. Since no code minification and other optimizations are performed in the `dev` phase, the real output size cannot be reflected, so it is recommended to analyze the output size in the `build` phase.

packages/document/builder-doc/docs/en/guide/optimization/optimize-bundle.md

@@ -30,15 +30,13 @@ npx yarn-deduplicate && yarn
 
 It is recommended to using lightweight libraries in your project, such as replacing [moment](https://momentjs.com/) with [day.js](https://day.js.org/).
 
-If you want to find out the large libraries in the project, you can add the [BUNDLE_ANALYZE=true](/en/api/config-performance.html#performancebundleanalyze) environment variable when building:
+If you want to find out the large libraries in the project, you can add the `BUNDLE_ANALYZE=true` environment variable when building:
 
 ```bash
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-After adding this parameter, Builder will generate a HTML file that analyzes the bundle size, you can manually open the file in the browser and view the detail of the bundle size. When an area is larger, it indicates that its corresponding bundle size is larger.
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png)
+See the [performance.bundleAnalyze](/api/config-performance.html#performancebundleanalyze) configuration for details.
 
 ## Adjust Browserslist
 

packages/document/builder-doc/docs/zh/config/performance/bundleAnalyze.md

@@ -1,30 +1,75 @@
 - **类型：** `Object | undefined`
 
-你有两种方式开启 `webpack-bundle-analyzer` 来分析构建产物的体积:
-
-- 添加环境变量 `BUNDLE_ANALYZE=true`；
-- 配置 `performance.bundleAnalyze`。
+用于开启 [webpack-bundle-analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer) 插件来分析产物体积。
 
-默认情况下，不会开启 `webpack-bundle-analyzer`，当开启之后它的配置如下:
+默认情况下，Builder 不会开启 `webpack-bundle-analyzer`。当开启该功能后，内部的默认配置如下:
 
 ```js
-{
+const defaultConfig = {
   analyzerMode: 'static',
   openAnalyzer: false,
   // target 为编译目标，如 `web`、`node` 等
   reportFilename: `report-${target}.html`,
-}
+};
+```
+
+### 启用 Bundle Analyze
+
+你有两种方式开启 `webpack-bundle-analyzer` 来分析构建产物的体积:
+
+- 添加环境变量 `BUNDLE_ANALYZE=true`，比如：
+
+```bash
+BUNDLE_ANALYZE=true pnpm build
+```
+
+- 配置 `performance.bundleAnalyze` 来固定开启：
+
+```js
+export default {
+  performance: {
+    bundleAnalyze: {},
+  },
+};
 ```
 
-你可以通过 `performance.bundleAnalyze` 来覆盖默认配置，比如：
+在启用后，Builder 会生成一个分析构建产物体积的 HTML 文件，并在 Terminal 中打印以下日志：
+
+```bash
+Webpack Bundle Analyzer saved report to /Project/my-project/dist/report-web.html
+```
+
+手动在浏览器中打开该文件，可以看到打包产物的瓦片图；区块的面积越大，说明该模块的体积越大。
+
+![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png)
+
+### 覆盖默认配置
+
+你可以通过 `performance.bundleAnalyze` 来覆盖默认配置，比如开启 `server` 模式：
 
 ```js
 export default {
   performance: {
-    bundleAnalyze: {
-      analyzerMode: 'server',
-      openAnalyzer: true,
-    },
+    bundleAnalyze: process.env.BUNDLE_ANALYZE
+      ? {
+          analyzerMode: 'server',
+          openAnalyzer: true,
+        }
+      : {},
   },
 };
 ```
+
+### Size 类型
+
+在 `webpack-bundle-analyzer` 的面板中，你可以在左上角控制 Size 类型（默认为 `Parsed`）：
+
+- `Stat`：从打包工具的 `stats` 对象中获取的体积，它反映了代码在压缩之前的体积。
+- `Parsed`：磁盘上的文件体积，它反映了代码在压缩之后的体积。
+- `Gzipped`：浏览器里请求的文件体积，它反映了代码在压缩和 gzip 后的体积。
+
+### 注意事项
+
+1. 开启 Server 模式会导致 `build` 进程不能正常退出。
+2. 开启 bundleAnalyzer 会降低构建性能。因此，在日常开发过程中不应该开启此配置项，建议通过 `BUNDLE_ANALYZE` 环境变量来按需开启。
+3. 由于 `dev` 阶段不会进行代码压缩等优化，无法反映真实的产物体积，因此建议在 `build` 阶段分析产物体积。

packages/document/builder-doc/docs/zh/guide/optimization/optimize-bundle.md

@@ -30,15 +30,13 @@ npx yarn-deduplicate && yarn
 
 建议将项目中体积较大的三方库替换为更轻量的库，比如将 [moment](https://momentjs.com/) 替换为 [day.js](https://day.js.org/)。
 
-如果你需要找出项目中体积较大的三方库，可以在执行构建时添加 [BUNDLE_ANALYZE=true](/api/config-performance.html#performancebundleanalyze) 环境变量：
+如果你需要找出项目中体积较大的三方库，可以在执行构建时添加 `BUNDLE_ANALYZE=true` 环境变量：
 
 ```bash
 BUNDLE_ANALYZE=true pnpm build
 ```
 
-添加该参数后，Builder 会生成一个分析构建产物体积的 HTML 文件，手动在浏览器中打开该文件，可以看到打包产物的瓦片图。区块的面积越大，说明该模块的体积越大。
-
-![](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/mwa-build-analyze-8784f762c1ab0cb20935829d5f912c4c.png)
+详见 [performance.bundleAnalyze](/api/config-performance.html#performancebundleanalyze) 配置项。
 
 ## 提升 Browserslist 范围