docs: improve documentation for file size diff

packages/core/src/types/config.ts

@@ -688,7 +688,10 @@ export type PrintFileSizeOptions = {
    */
   exclude?: (asset: PrintFileSizeAsset) => boolean;
   /**
-   * Whether to show file size difference compared to the previous build.
+   * Controls whether file size differences are displayed relative to the previous build.
+   * When this option is enabled, Rsbuild records a snapshot of all output file sizes after
+   * each build. On subsequent builds, Rsbuild compares the current sizes against the previous
+   * snapshot and shows the change inline in parentheses.
    * @default false
    */
   diff?: boolean;

website/docs/en/config/performance/print-file-size.mdx

@@ -234,11 +234,11 @@ export default {
 - **Type:** `boolean`
 - **Default:** `false`
 
-Whether to show file size difference compared to the previous build.
+Controls whether file size differences are displayed relative to the previous build.
 
-When enabled, Rsbuild will snapshot the file sizes after each build and display the difference inline in parentheses on subsequent builds.
+When this option is enabled, Rsbuild records a snapshot of all output file sizes after each build. On subsequent builds, Rsbuild compares the current sizes against the previous snapshot and shows the change inline in parentheses.
 
-To enable the diff display:
+To enable diff output:
 
 ```ts title="rsbuild.config.ts"
 export default {
@@ -250,7 +250,7 @@ export default {
 };
 ```
 
-The output will show size changes inline:
+On the second build, the output begins to include inline size deltas:
 
 ```
 File (web)                              Size                  Gzip
@@ -261,12 +261,12 @@ dist/static/css/index.2960ac62.css      0.35 kB (+0.35 kB)    0.26 kB (+0.26 kB)
                                Total:   143.0 kB (+2.15 kB)   46.3 kB (+0.66 kB)
 ```
 
-- Size increases are shown in **red** with a `+` prefix
-- Size decreases are shown in **green** with a `-` prefix
-- Unchanged files don't show any diff
+- Increases are highlighted in red with a `+` prefix
+- Decreases are highlighted in green with a `-` prefix
+- Files with no change omit the diff indicator
 
 :::tip
-The snapshot file is stored in `<root>/node_modules/.cache/rsbuild/file-sizes-[hash].json`, where `[hash]` is the hash of the Rsbuild config file path.
+Snapshots are stored at `<root>/node_modules/.cache/rsbuild/file-sizes-[hash].json`, where [hash] is derived from the Rsbuild configuration file path.
 :::
 
 ## Version history

website/docs/zh/config/performance/print-file-size.mdx

@@ -227,3 +227,49 @@ export default {
   },
 };
 ```
+
+### diff
+
+- **类型:** `boolean`
+- **默认值:** `false`
+
+控制是否展示相较于上一次构建的文件体积差异。
+
+启用该选项后，Rsbuild 会在每次构建完成后记录所有输出文件的体积快照，随后在下一次构建时 Rsbuild 会将当前构建的文件体积与上一份快照进行对比，并在输出中以括号形式展示体积差异。
+
+启用方式如下：
+
+```ts title="rsbuild.config.ts"
+export default {
+  performance: {
+    printFileSize: {
+      diff: true,
+    },
+  },
+};
+```
+
+从第二次构建开始，输出中将显示体积变化信息：
+
+```
+File (web)                              Size                  Gzip
+dist/static/js/lib-react.b0714b60.js    140.4 kB (+2.1 kB)    45.0 kB (+0.5 kB)
+dist/static/js/index.f3fde9c7.js        1.9 kB (-0.3 kB)      0.97 kB (-0.1 kB)
+dist/static/css/index.2960ac62.css      0.35 kB (+0.35 kB)    0.26 kB (+0.26 kB)
+
+                               Total:   143.0 kB (+2.15 kB)   46.3 kB (+0.66 kB)
+```
+
+- 文件体积增加会以红色并带有 `+` 前缀
+- 文件体积减少会以绿色并带有 `-` 前缀
+- 若文件体积无变化，则不会显示差异信息
+
+:::tip
+快照文件存储在 `<root>/node_modules/.cache/rsbuild/file-sizes-[hash].json`，其中 `[hash]` 基于 Rsbuild 配置文件路径生成。
+:::
+
+## 版本历史
+
+| 版本    | 变更内容         |
+| ------- | ---------------- |
+| v1.6.13 | 新增 `diff` 选项 |