> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.

# 浏览器兼容性

## Browserslist 配置

Modern.js 支持通过三种方式来设置 Web 应用需要兼容的浏览器范围。

### 方式一：通过`.browserslistrc` 文件配置

Modern.js 支持设置 Web 应用需要兼容的浏览器范围，你可以在 `.browserslistrc` 文件里设置 [Browserslist](https://browsersl.ist/) 的值。

当你创建一个新的 Modern.js 项目时，默认会包含一份 `.browserslistrc` 配置，这表示 JavaScript 代码会被编译至 ES6 格式。

```yaml title=".browserslistrc"
chrome >= 87
edge >= 88
firefox >= 78
safari >= 14
```

当项目中未指定 `overrideBrowserslist` 配置时，该 `.browserslistrc` 文件会默认生效。

### 方式二：通过 package.json 配置

你也可以在 `package.json` 文件中设置 `browserslist` 字段来配置 browserslist:

```json title="package.json"
{
  "browserslist": [
    "chrome >= 87"
    // 其他浏览器的配置...
  ]
}
```

### 方式三：通过 `output.overrideBrowserslist` 配置

你也可以在 `modern.config.js` 文件中设置 [`output.overrideBrowserslist`](/zh/configure/app/output/override-browserslist.md) 字段来配置 browserslist:

```js title="modern.config.js"
export default {
  output: {
    overrideBrowserslist: [
      'chrome >= 87',
      // 其他浏览器的配置...
    ],
  },
};
```

### 配置优先级

`overrideBrowserslist` 配置的优先级高于项目中的 `.browserslistrc` 配置文件和 package.json 中的 `browserslist` 字段。

大多数场景下，推荐优先使用 `.browserslistrc` 文件，而不是使用 `overrideBrowserslist` 配置。因为 `.browserslistrc` 文件是官方定义的配置文件，通用性更强，可以被社区中的其他库识别。

:::tip
请查看 [Rsbuild - 设置浏览器范围](https://v2.rsbuild.rs/zh/guide/advanced/browserslist) 来了解更多内容。
:::


## Polyfill

### 编译时 Polyfill

Modern.js 在编译时默认通过 [core-js](https://github.com/zloirock/core-js) 引入对应的 Polyfill 代码。

默认情况下会根据项目 Browserslist 的设置情况引入所需的 Polyfill 代码， 这样基本不用再担心项目源码和第三方依赖的 Polyfill 问题了，但是因为包含了一些没有用到的 Polyfill 代码，所以最终的包大小可能会有所增加。

:::info
对于明确第三方依赖不需要 Polyfill 的场景，可以设置 [`output.polyfill`](/zh/configure/app/output/polyfill.md) 为 `usage`, 这样 Babel 编译时只会根据代码中使用到的语法引入 Polyfill 代码。

:::

### 运行时按需 Polyfill

Modern.js 中还提供了基于浏览器 [UA](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Headers/User-Agent) 信息的运行时按需 Polyfill 方案，相比于 Babel 优势如下：

- 不会插入到代码中，只根据访问页面的设备，按需下发 Polyfill 代码 ，减少整体代码体积。
- 相同浏览器会公用一份 Polyfill 代码。因此，随着项目越来越多，基于 UA 的 Polyfill 代码下发速度会越来越快，综合速度超过常规方案。

Modern.js 提供了 `@modern-js/plugin-polyfill` 插件来实现该功能，可以通过安装该插件来开启该功能：


```sh [npm]
npm install @modern-js/plugin-polyfill
```

```sh [yarn]
yarn add @modern-js/plugin-polyfill
```

```sh [pnpm]
pnpm add @modern-js/plugin-polyfill
```

然后在 `modern.config.ts` 中注册 Polyfill 插件:

```ts title="modern.config.ts"
import { polyfillPlugin } from '@modern-js/plugin-polyfill';

export default defineConfig({
  plugins: [..., polyfillPlugin()],
});
```

配置 `output.polyfill` 为 `ua` 并且执行 `pnpm run build && pnpm run serve` 启动服务器后，访问页面可以看到 HTML 产物中包含如下脚本:

```js
<script src="/__polyfill__" crossorigin></script>
```

在 Chrome 51 下访问页面可以看到 `http://localhost:8080/__polyfill__` 返回内容如下:

![ua-polyfill](https://lf3-static.bytednsdoc.com/obj/eden-cn/aphqeh7uhohpquloj/modern-js/docs/ua-polyfill.png)

:::caution 注意
该功能只有在使用 Modern.js 内置的 Web Server 时才会生效。

如果有自定义模版的需求，请参考 [HTML 模板](/zh/guides/basic-features/html.md)。通过 `html.template` 或 `tools.html` 手动修改模版时，可能会导致该功能无法正确生效。
:::