实验特性配置

title: 实验特性配置
sort: 19
contributors:

• EugeneHlushko
• wizardofhogwarts
• chenxsan
• anshumanv
• snitin315
• burhanuday

experiments

boolean: false

experiments 选项在 webpack 5 中引入，用于让用户能够启用和尝试实验性功能。

W> 由于实验性功能具有宽松的语义化版本控制，并且可能包含破坏性变更，请确保将 webpack 版本固定到 minor 版本，例如 webpack: ~5.4.3 而不是 webpack: ^5.4.3，或者在使用 experiments 时使用 lockfile。

可用选项：

• asyncWebAssembly：根据更新后的规范支持新的 WebAssembly，它将 WebAssembly 模块变为异步模块。自 webpack 5.109.0 起默认为 'auto'，即除非为 WebAssembly 文件注册了 loader，否则启用内置支持。
• backCompat
• buildHttp
• cacheUnaffected
• css
• deferImport
• futureDefaults
• html
• lazyCompilation
• outputModule
• typescript
• sourceImport
• syncWebAssembly：像 webpack 4 那样支持旧的 WebAssembly。
• layers：启用模块和 chunk 层级，自 5.102.0 起已移除并且无需额外选项即可工作。
• topLevelAwait：当在顶层使用 await 时，将模块转换为 async 模块。从 webpack 版本 5.83.0 开始（但在之前的版本中，可以通过将 experiments.topLevelAwait 设置为 true 来启用），此功能默认启用，自 5.102.0 起已移除并且无需额外选项即可工作。

webpack.config.js

export default {
  // ...
  experiments: {
    asyncWebAssembly: true,
    buildHttp: true,
    lazyCompilation: true,
    outputModule: true,
    sourceImport: true,
    syncWebAssembly: true,
    topLevelAwait: true,
  },
};

experiments.backCompat

启用向后兼容层，并对许多 webpack 4 API 发出弃用警告。

• 类型：boolean

export default {
  // ...
  experiments: {
    backCompat: true,
  },
};

experiments.buildHttp

启用后，webpack 可以构建以 http(s): 协议开头的远程资源。

• 类型：

  • (string | RegExp | ((uri: string) => boolean))[]

    experiments.buildHttp.allowedUris 的简写形式。

  • HttpUriOptions

    ts 复制代码

    {
      allowedUris: (string|RegExp|(uri: string) => boolean)[],
      cacheLocation?: false | string,
      frozen?: boolean,
      lockfileLocation?: string,
      upgrade?: boolean
    }

• 可用版本：5.49.0+

• 示例

  webpack.config.js

  js 复制代码

  export default {
    // ...
    experiments: {
      buildHttp: true,
    },
  };

  js 复制代码

  // src/index.js
  import pMap1 from "https://cdn.skypack.dev/p-map";
  
  // 启用 `buildHttp` 后，webpack 会像处理普通本地模块一样构建 pMap1
  console.log(pMap1);

experiments.buildHttp.allowedUris

允许的 URI 列表。

• 类型：(string|RegExp|(uri: string) => boolean)[]

• 示例

  webpack.config.js

  js 复制代码

  export default {
    // ...
    experiments: {
      buildHttp: {
        allowedUris: [
          "http://localhost:9990/",
          "https://raw.githubusercontent.com/",
        ],
      },
    },
  };

experiments.buildHttp.cacheLocation

定义缓存远程资源的位置。

• 类型

  • string
  • false

• 示例

  webpack.config.js

  js 复制代码

  export default {
    // ...
    experiments: {
      buildHttp: {
        cacheLocation: false,
      },
    },
  };

默认情况下，webpack 会使用 <compiler-name.>webpack.lock.data/ 进行缓存，但你可以通过将其值设置为 false 来禁用缓存。

请注意，你应该将 experiments.buildHttp.cacheLocation 下的文件提交到版本控制系统中，因为在 production 构建期间不会发起任何网络请求。

experiments.buildHttp.frozen

冻结远程资源和 lockfile。对 lockfile 或资源内容的任何修改都将导致错误。

• 类型：boolean

experiments.buildHttp.lockfileLocation

定义存储 lockfile 的位置。

• 类型：string

默认情况下，webpack 会生成一个 <compiler-name.>webpack.lock 文件。请确保将其提交到版本控制系统中。在 production 构建期间，webpack 将根据 lockfile 和 experiments.buildHttp.cacheLocation 下的缓存来构建以 http(s): 协议开头的模块。

experiments.buildHttp.proxy

指定用于获取远程资源的代理服务器。

• 类型：string

默认情况下，webpack 会从 http_proxy（不区分大小写）环境变量中推断用于获取远程资源的代理服务器。不过，你也可以通过 proxy 选项指定代理。

experiments.buildHttp.upgrade

检测远程资源的变化并自动升级它们。

• 类型：boolean

experiments.css

启用原生 CSS 支持。请注意，这仍然是一个正在开发中的实验性功能，将在 webpack v6 中默认启用，但你可以在 GitHub 上跟踪进展。

• 类型：boolean | 'auto'
• 默认值：'auto'

自 webpack 5.109.0 起，该选项默认为 'auto'：除非 module.rules 中已有带 loader（或显式模块类型）的规则匹配 .css 或 .module.css 文件，否则启用内置 CSS 支持，因此现有的 css-loader/mini-css-extract-plugin 配置可以保持不变。将其设置为 true 以强制使用原生支持，或设置为 false 以完全禁用。experiments.futureDefaults 会将其解析为 true。

实验性功能：

• CSS Modules 支持：webpack 会为每个 CSS 类生成唯一的名称。使用 .module.css 扩展名来启用 CSS Modules。

  webpack 原生支持 CSS Modules 的 composes 属性，允许你从同一文件、其他 CSS 模块或全局类中组合类：

  css 复制代码

  /* styles.module.css */
  .base {
    color: blue;
  }
  
  .button {
    composes: base;
    padding: 10px;
  }
  
  .primary {
    composes: button;
    background: blue;
  }
  
  /* 从另一个 CSS 模块中组合 */
  .composed {
    composes: className from "./other.module.css";
  }
  
  /* 从全局类中组合 */
  .globalComposed {
    composes: global-class from global;
  }

• 解析 package.json 文件中的样式特定字段：webpack 会查找 package.json 文件中的 style 字段，如果在 CSS 文件内部有导入，则使用该字段。

  例如，如果你在 CSS 文件中添加 @import 'bootstrap';，webpack 会在 node_modules 中查找 bootstrap，并使用其 package.json 中的 style 字段。如果找不到 style 字段，webpack 将使用 main 字段以保持向后兼容。

• CSS 文件的内容哈希：webpack 会为 CSS 文件生成内容哈希，并将其用于文件名中。这对于长期缓存非常有用。

• CSS 提取：webpack 会将 CSS 提取到单独的文件中。此功能替代了 mini-css-extract-plugin 和 css-loader 的需求，因为它提供了原生支持。

• CSS 导入：webpack 会将 CSS 导入内联到生成的 CSS 文件中。

• 热模块替换（HMR）：webpack 支持 CSS 文件的 HMR。这意味着对 CSS 文件所做的更改将无需完全重新加载页面即可反映在浏览器中。

• CSS Modules 的作用域提升（模块拼接）。当
  optimization.concatenateModules
  启用时，exportType 为 text、css-style-sheet、
  style 或 link 的 CSS Modules 会被拼接为单个模块实例，而不是作为独立的运行时实例存在。这减少了开销，并为 CSS 密集型打包产物生成更小的输出。

• @value 标识符可以用作 @import 的路径参数以及 url() 引用中，因此共享路径和资源可以定义一次并在多个样式表中复用。带引号（"./x"、'./x'）和不带引号（./x）的形式都被接受，并会通过 webpack 常规的资源管线进行解析。

  css 复制代码

  @value path: "./other.module.css";
  @import path;
  
  @value bg: "./image.png";
  
  .a {
    background: url(bg);
  }

experiments.cacheUnaffected

启用对未更改且仅引用未更改模块的模块进行额外的内存缓存。

• 类型：boolean

默认值为 futureDefaults 的值。

experiments.deferImport

启用 tc39 提案 the import defer proposal 的支持。这允许将模块的求值延迟到首次使用时。这对于在由于 import() 的异步特性而无法使用时，需要同步延迟代码执行的情况非常有用。

• 类型：boolean

此功能要求运行时环境支持 Proxy（ES6）。

启用以下语法：

{/* eslint-skip */}

import defer * as module from "module-name";
import * as module2 from /* webpackDefer: true */ "module-name2";

// 或者使用动态导入
import.defer("module-name3");
import(/* webpackDefer: true */ "module-name4");

export function f() {
  // module-name 被同步求值，然后对其调用 doSomething()。
  module.doSomething();
}

魔术注释（/* webpackDefer: true */）的限制

建议将魔术注释放在 from 关键字之后。其他位置可能有效，但尚未经过测试。

将魔术注释放在 import 关键字之后与文件系统缓存不兼容。

{/* eslint-skip */}

import /* webpackDefer: true */ * as ns from "..."; // 已知不可用
import * as ns from /* webpackDefer: true */ "..."; // 推荐写法

你应该确保你的 loader 不会移除魔术注释。

TypeScript、Babel、SWC 和 Flow.js 可以配置为保留魔术注释。

Esbuild 不兼容此功能（参见 evanw/esbuild#1439 和 evanw/esbuild#309），但它可能会在将来支持此功能。

// webpack.config.js
export default {
  // ...
  experiments: {
    asyncWebAssembly: true,
    sourceImport: true,
  },
};

// 静态形式
import source wasmModule from "./module.wasm";

// 动态形式
const wasmModule2 = await import.source("./module.wasm");

const instance = await WebAssembly.instantiate(wasmModule);

export default {
  // ...
  experiments: {
    futureDefaults: true,
  },
};

export default {
  // ...
  experiments: {
    html: true,
  },
};

// src/index.js
import page from "./page.html";

document.documentElement.innerHTML = page;

<!-- src/page.html -->
<!doctype html>
<html>
  <head>
    <style>
      @import "./reset.css";

      body {
        background: url("./bg.png");
      }
    </style>
  </head>
  <body>
    ...
  </body>
</html>

<!-- src/page.html -->
<!doctype html>
<html>
  <body>
    <script type="module">
      import { greet } from "./lib.js";
      greet("world");
    </script>

    <script>
      console.log("classic inline script");
    </script>
  </body>
</html>

<!-- src/page.html -->
<!doctype html>
<html>
  <head>
    <link rel="modulepreload" href="./preloaded.js" />
  </head>
  <body>
    <script src="./entry.js"></script>
    <script src="./second.js"></script>
  </body>
</html>

export default {
  experiments: { html: true },
  entry: "./src", // 解析到 ./src/index.html
};

export default {
  experiments: {
    outputModule: true,
  },
};

export default {
  experiments: {
    typescript: true,
  },
  entry: "./src/index.ts",
};