docs: add web workers browser compatibility tips (#6282)

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

Author: 9aoy

website/docs/en/config/output/polyfill.mdx

@@ -33,6 +33,10 @@ export default {
 };
 ```
 
+:::tip
+It should be noted that when you bundle page with [Web Workers](/guide/basic/web-workers), the `entry` mode is not applicable to Web Workers because the Web Workers thread is isolated from the main thread (page), and the `usage` mode can be used at this time.
+:::
+
 ### off
 
 With `output.polyfill` set to `'off'`, Rsbuild doesn't inject polyfills. You need to handle code compatibility yourself.

website/docs/en/guide/basic/web-workers.mdx

@@ -98,6 +98,18 @@ worker.postMessage(10);
 
 For detailed discussions on cross-domain issues, please refer to [Discussions - webpack 5 web worker support for CORS?](https://github.com/webpack/webpack/discussions/14648)
 
+### Browser compatibility
+
+When your application includes both main-thread code and Web Workers created with `new Worker`, note that Web Workers run in isolated threads and do not share the main-thread environment. As a result, Rsbuild’s polyfill [entry mode](/guide/advanced/browser-compatibility#entry-mode) does not apply to Web Workers. In this case, it’s recommended to use the [usage mode](/guide/advanced/browser-compatibility#usage-mode) to inject the required polyfills directly into each Web Worker.
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    polyfill: 'usage',
+  },
+};
+```
+
 ## Standalone build
 
 Rsbuild supports standalone building of Web Workers bundles. When you need to configure independent build options for Web Workers or provide Web Workers for use by other applications, you can use the following methods.

website/docs/zh/config/output/polyfill.mdx

@@ -33,6 +33,10 @@ export default {
 };
 ```
 
+:::tip
+需要注意的是，当你将页面与 [Web Workers](/guide/basic/web-workers) 一起打包时，由于 Web Workers 线程与主线程（页面）环境隔离，`entry` 方案对 Web Workers 并不适用，此时可以使用 `usage` 方案。
+:::
+
 ### off
 
 当 `output.polyfill` 配置为 `'off'` 时，Rsbuild 不会注入 polyfills，你需要自行处理代码的兼容性。

website/docs/zh/guide/basic/web-workers.mdx

@@ -98,6 +98,18 @@ worker.postMessage(10);
 
 关于跨域问题的详细讨论可参考 [Discussions - webpack 5 web worker support for CORS?](https://github.com/webpack/webpack/discussions/14648)
 
+### 浏览器兼容性
+
+当你的应用中既包含主线程代码，也包含通过 `new Worker` 创建的 Web Worker 时，需要注意：由于 Web Worker 运行在独立的线程中，与主线程环境隔离，Rsbuild 提供的 polyfill [entry 方案](/guide/advanced/browser-compatibility#entry-方案) 无法在 Web Worker 中生效。此时，建议改用 [usage 方案](/guide/advanced/browser-compatibility#usage-方案)，为 Web Worker 单独注入所需的 polyfill 代码。
+
+```ts title="rsbuild.config.ts"
+export default {
+  output: {
+    polyfill: 'usage',
+  },
+};
+```
+
 ## 独立构建
 
 Rsbuild 支持独立构建 Web Workers 产物。当你需要为 Web Workers 配置独立的构建选项，或将 Web Workers 提供给其他应用使用时，可以使用以下方法。