docs: 完善转es5文档

Author: yushijie1

docs/h5.md

@@ -8,7 +8,17 @@ title: H5
 
 ### ES5
 
-默认配置下，`@babel/preset-env` 的 `target` 配置为：
+#### JS 版本
+
+为了更高的编译效率和更小的产物体积，V4 开始默认的 browserslist 配置调整为：
+
+```json
+{
+  "browserslist": ["defaults and fully supports es6-module", "maintained node versions"]
+}
+```
+
+> 如不存在 browserslist 相关配置，则会使用 `@babel/preset-env` 的 `target` 默认配置，如下：
 
 ```js
 targets = {
@@ -17,25 +27,88 @@ targets = {
 }
 ```
 
-如果需要兼容更低版本的系统，请修改在项目根目录的 `babel.config.js` 中修改 `babel-preset-taro` 的配置。[文档](/docs/babel-config)
+#### 将代码编译为 ES5
+
+V4.0.8 开始使用脚手架创建项目时新增了`是否编译为ES5`的确认项，如选择`是`，生成的项目会在生产模式打包时将全量代码编译为 ES5。需要注意的是：编译为 ES5 会影响编译效率和产物体积。
 
-#### babel-loader
+也可以通过如下配置将代码编译为 ES5：
 
-为了提升编译速度，Taro 给 `babel-loader` 设置了 `exclude` 属性。对于 `node_modules` 里（除了命名含有 `taro`）的依赖，都不经过 babel 编译。`babel-loader` 配置请看 [Github](https://github.com/NervJS/taro/blob/4aa08d541b1c5221bf420fc0f4a305960e22aa0a/packages/taro-webpack-runner/src/util/chain.ts#L502-L510)。
+1. 修改 browserslist
 
-因此需要注意以下问题：
+```json title='package.json'
+{
+  "browserslist": {
+    "development": ["defaults and fully supports es6-module", "maintained node versions"],
+    "production": ["last 3 versions", "Android >= 4.1", "ios >= 8"]
+  }
+}
+```
+
+2. 设置 BROWSERSLIST_ENV 环境变量，以便在不同环境使用不同的 browserslist 配置
+
+```js title='config/index.js'
+process.env.BROWSERSLIST_ENV = process.env.NODE_ENV
+```
 
-- `@tarojs/components` 默认不经 Babel 编译，但 `3.2.10` 之前没有编译出 ES5 包，请更新到 `3.2.10` 及以上版本。
-- 默认不编译 `node_modules` 里的依赖，如有兼容性需求，请手动使用 [WebpackChain](config-detail#h5webpackchain) 修改 `babel-loader` 的 `exclude` 属性。
+3. 修改 `babel-preset-taro` 的配置。[文档](babel-config#usebuiltins)
 
-#### Android 4.4
+```js title='babel.config.js'
+useBuiltIns: process.env.TARO_ENV === 'h5' ? 'usage' : false
+```
+
+4. 修改编译范围
+
+```js title='config/prod.js'
+// 编译器为 webpack 时
+h5: {
+    compile: {
+      include: [
+        // 确保产物为 ES5，如可以确认包含 ES6 代码的 node_modules，则可修改正则采用白名单方式缩小编译范围，以提升编译速度
+        filename => /node_modules\/(?!(@babel|core-js|style-loader|css-loader|react|react-dom))/.test(filename)
+      ]
+    }
+}
+
+// 编译器为 vite 时
+h5: {
+  legacy: true,
+}
+```
+
+> 小程序可根据自己需求决定是否需要配置和 H5 一样的 include。
+
+> V4.0.8 之前的版本由于默认 exclude 了 `@tarojs/components`，而 exclude 优先级高于 include，所以需要按下述方法配置：
+
+```js title='config/prod.js'
+h5: {
+  webpackChain (chain) {
+    chain.merge({
+      module: {
+        rule: {
+          myloader: {
+            test: /\.js$/,
+            use: [
+              {
+                loader: 'babel-loader',
+                options: {},
+              },
+            ],
+          },
+        },
+      },
+    });
+  }
+}
+```
 
-兼容安卓 4.4 请确认完成了以下操作：
+#### 其他注意事项
 
-- Taro 使用 `v3.2.15+` 版本。
-- 使用兼容性组件库（暂时只支持 React）。
-- 合理配置 `babel-preset-taro`，安装 `corejs3`。
-- 如还是遇到 `Promise undefined` 的问题，可在 `index.html` 中手动引入一个 Promise 的 polyfill。
+- Taro 内置的 `babel-loader` 配置请查看 [H5WebpackModule](https://github.com/NervJS/taro/blob/8317e63d0345e18dedcccc34c3ae672ef829f304/packages/taro-webpack5-runner/src/webpack/H5WebpackModule.ts#L258)。
+- V4.0.8 开始 `@tarojs/components` 也会经过 Babel 编译。
+- 除了通过 `h5.compile` 来新增 include 和 exclude，您也可使用 [WebpackChain](config-detail#h5webpackchain) 来修改 Taro 内置的 `babel-loader` 配置。
+- 如果还会遇到兼容性问题（如 Android 4.4），可考虑以下几点：
+  - 使用兼容性组件库（暂时只支持 React），见：[兼容性组件库](h5#react-兼容性组件库)。
+  - 如遇到 `Promise undefined` 等问题，可在 `index.html` 中手动引入一个 Promise 的 polyfill。
 
 ### 组件库