web-infra-dev · chenjiahan · Oct 14, 2025 · Oct 14, 2025
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -1597,10 +1597,11 @@ export interface HtmlConfig {
     { entryName: string }
   >;
   /**
-   * Set the loading mode of the `<script>` tag.
-   * - `'defer'`: The `<script>` tags are rendered with `defer` attribute.
-   * - `'module'`: The `<script>` tags are rendered with `type="module"` attribute.
-   * - `'blocking'`: The `<script>` tags are rendered without `defer` or `async` attribute.
+   * Specifies how `<script>` tags generated by Rsbuild are loaded.
+   * - `'defer'`: Adds the `defer` attribute so scripts load in parallel and run after
+   * the document has been parsed.
+   * - `'module'`: Adds `type="module"` to enable ES modules semantics.
+   * - `'blocking'`: No `defer` or `async`, scripts execute immediately in order.
    * @default 'defer'. If `output.module` is enabled, the value is always `'module'`.
    */
   scriptLoading?: ScriptLoading;

diff --git a/website/docs/en/config/html/script-loading.mdx b/website/docs/en/config/html/script-loading.mdx
@@ -3,11 +3,19 @@
 - **Type:** `'defer' | 'blocking' | 'module'`
 - **Default:** `'defer'`
 
-Used to set how `<script>` tags are loaded.
+Specifies how `<script>` tags generated by Rsbuild are loaded.
+
+- `'defer'`: Adds the `defer` attribute so scripts load in parallel and run after the document has been parsed.
+- `'module'`: Adds `type="module"` to enable ES modules semantics.
+- `'blocking'`: No `defer` or `async`, scripts execute immediately in order.
+
+:::tip
+If [output.module](/config/output/module) is enabled, the value is always `'module'`.
+:::
 
 ### defer
 
-By default, the `<script>` tag generated by Rsbuild will automatically set the `defer` attribute to avoid blocking the parsing and rendering of the page.
+By default, the `<script>` tag generated by Rsbuild will automatically set the [`defer` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer) to avoid blocking the parsing and rendering of the page.
 
 ```html
 <head>
@@ -17,46 +25,46 @@ By default, the `<script>` tag generated by Rsbuild will automatically set the `
 ```
 
 :::tip
-When the browser encounters a `<script>` tag with the defer attribute, it will download the script file asynchronously without blocking the parsing and rendering of the page. After the page is parsed and rendered, the browser executes the `<script>` tags in the order they appear in the document.
+When the browser encounters a `<script>` tag with the `defer` attribute, it will download the script file asynchronously without blocking the parsing and rendering of the page. After the page is parsed and rendered, the browser executes the `<script>` tags in the order they appear in the document.
 :::
 
-### blocking
+### module
 
-Setting `scriptLoading` to `blocking` will remove the `defer` attribute, and the script is executed synchronously, which means it will block the browser's parsing and rendering process until the script file is downloaded and executed.
+When `scriptLoading` is set to `module`, the script can support ES modules syntax, and the browser will automatically delay the execution of these scripts by default, which is similar to `defer`.
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   html: {
-    inject: 'body',
-    scriptLoading: 'blocking',
+    scriptLoading: 'module',
   },
 };
 ```
 
-When you need to set `blocking`, it is recommended to set `html.inject` to `'body'` to avoid page rendering being blocked.
-
 ```html
-<head></head>
-<body>
-  <script src="/static/js/main.js"></script>
-</body>
+<head>
+  <script type="module" src="/static/js/main.js"></script>
+</head>
+<body></body>
 ```
 
-### module
+### blocking
 
-When `scriptLoading` is set to `module`, the script can support ES modules syntax, and the browser will automatically delay the execution of these scripts by default, which is similar to `defer`.
+Setting `scriptLoading` to `blocking` will remove the `defer` attribute, and the script is executed synchronously, which means it will block the browser's parsing and rendering process until the script file is downloaded and executed.
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   html: {
-    scriptLoading: 'module',
+    inject: 'body',
+    scriptLoading: 'blocking',
   },
 };
 ```
 
+When you need to set `blocking`, it is recommended to set [html.inject](/config/html/inject) to `'body'` to avoid page rendering being blocked.
+
 ```html
-<head>
-  <script type="module" src="/static/js/main.js"></script>
-</head>
-<body></body>
+<head></head>
+<body>
+  <script src="/static/js/main.js"></script>
+</body>
 ```
diff --git a/website/docs/zh/config/html/script-loading.mdx b/website/docs/zh/config/html/script-loading.mdx
@@ -3,11 +3,19 @@
 - **类型：** `'defer' | 'blocking' | 'module'`
 - **默认值：** `'defer'`
 
-用于设置 `<script>` 标签的加载方式。
+指定由 Rsbuild 生成的 `<script>` 标签的加载方式。
+
+- `'defer'`：添加 `defer` 属性，使脚本并行加载并在文档解析完成后执行。
+- `'module'`：添加 `type="module"` 属性，以启用 ES modules 语义。
+- `'blocking'`：不添加 `defer` 或 `async`，脚本将按顺序立即执行。
+
+:::tip 提示
+如果启用了 [output.module](/config/output/module)，该值将始终为 `'module'`。
+:::
 
 ### defer
 
-默认情况下，Rsbuild 生成的 `<script>` 标签会自动设置 `defer` 属性，以避免阻塞页面的解析和渲染。
+默认情况下，Rsbuild 生成的 `<script>` 标签会自动设置 [`defer` 属性](https://developer.mozilla.org/zh-CN/docs/Web/HTML/Reference/Elements/script#defer)，以避免阻塞页面的解析和渲染。
 
 ```html
 <head>
@@ -17,46 +25,46 @@
 ```
 
 :::tip
-当浏览器遇到带有 defer 属性的 `<script>` 标签时，它会异步地下载脚本文件，不会阻塞页面的解析和渲染。在页面解析和渲染完成后，浏览器会按照 `<script>` 标签在文档中出现的顺序依次执行它们。
+当浏览器遇到带有 `defer` 属性的 `<script>` 标签时，它会异步地下载脚本文件，不会阻塞页面的解析和渲染。在页面解析和渲染完成后，浏览器会按照 `<script>` 标签在文档中出现的顺序依次执行它们。
 :::
 
-### blocking
+### module
 
-将 `scriptLoading` 设置为 `blocking` 可以移除 `defer` 属性，此时脚本是同步执行的，这意味着它会阻塞浏览器的解析和渲染过程，直到脚本文件被下载并执行完毕。
+将 `scriptLoading` 设置为 `module` 时，可以让脚本支持 ES modules 语法，同时浏览器也会自动默认延迟执行这些脚本，效果与 `defer` 类似。
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   html: {
-    inject: 'body',
-    scriptLoading: 'blocking',
+    scriptLoading: 'module',
   },
 };
 ```
 
-当你需要设置 `blocking` 时，建议把 `html.inject` 设置为 `body`，避免页面渲染被阻塞。
-
 ```html
-<head></head>
-<body>
-  <script src="/static/js/main.js"></script>
-</body>
+<head>
+  <script type="module" src="/static/js/main.js"></script>
+</head>
+<body></body>
 ```
 
-### module
+### blocking
 
-将 `scriptLoading` 设置为 `module` 时，可以让脚本支持 ES modules 语法，同时浏览器也会自动默认延迟执行这些脚本，效果与 `defer` 类似。
+将 `scriptLoading` 设置为 `blocking` 可以移除 `defer` 属性，此时脚本是同步执行的，这意味着它会阻塞浏览器的解析和渲染过程，直到脚本文件被下载并执行完毕。
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   html: {
-    scriptLoading: 'module',
+    inject: 'body',
+    scriptLoading: 'blocking',
   },
 };
 ```
 
+当你需要设置 `blocking` 时，建议把 [html.inject](/config/html/inject) 设置为 `body`，避免页面渲染被阻塞。
+
 ```html
-<head>
-  <script type="module" src="/static/js/main.js"></script>
-</head>
-<body></body>
+<head></head>
+<body>
+  <script src="/static/js/main.js"></script>
+</body>
 ```