docs: improve output configuration (#4657)

chenjiahan · web-flow · commit 4828c3055bbe · 2025-02-26T09:24:18.000+08:00
diff --git a/packages/core/src/types/config.ts b/packages/core/src/types/config.ts
@@ -1006,12 +1006,12 @@ export interface OutputConfig {
    */
   externals?: Externals;
   /**
-   * Set the directory of the dist files.
-   * Rsbuild will output files to the corresponding subdirectory according to the file type.
+   * Set the directory of the output files.
+   * Rsbuild will emit files to the specified subdirectory according to the file type.
    */
   distPath?: DistPathConfig;
   /**
-   * Sets the filename of dist files.
+   * Sets the filename of output files.
    */
   filename?: FilenameConfig;
   /**
diff --git a/website/docs/en/config/output/dist-path.mdx b/website/docs/en/config/output/dist-path.mdx
@@ -25,8 +25,8 @@ type DistPathConfig = {
 const defaultDistPath = {
   root: 'dist',
   html: './',
-  js: isServer ? '' : 'static/js',
-  jsAsync: isServer ? '' : 'static/js/async',
+  js: output.target === 'node' ? '' : 'static/js',
+  jsAsync: output.target === 'node' ? '' : 'static/js/async',
   css: 'static/css',
   cssAsync: 'static/css/async',
   svg: 'static/svg',
@@ -38,9 +38,15 @@ const defaultDistPath = {
 };
 ```
 
-Set the directory of the dist files. Rsbuild will output files to the corresponding subdirectory according to the file type.
+Set the directory of the output files. Rsbuild will emit files to the specified subdirectory according to the file type.
 
-Detail:
+> See [Output files](/guide/basic/output-files) for more information.
+
+## File types
+
+`output.distPath` can be set differently for different file types.
+
+Here are the details of each `output.distPath` option:
 
 - `root`: The root directory of all output files.
 - `html`: The output directory of HTML files.
@@ -55,19 +61,19 @@ Detail:
 - `media`: The output directory of media assets, such as videos.
 - `assets`: The output directory of other static assets. Such as the assets defined in [Extend Asset Types](/guide/basic/static-assets#extend-asset-types).
 
-### Root directory
+## Root directory
 
 The `root` is the root directory of the build artifacts and can be specified as a relative or absolute path. If the value of `root` is a relative path, it will be appended to the project's root directory to form an absolute path.
 
 Other directories can only be specified as relative paths and will be output relative to the `root` directory.
 
-### Example
+## Example
 
 The JavaScript files will be output to the `distPath.root` + `distPath.js` directory, which is `dist/static/js`.
 
 To output JavaScript files to the `build/resource/js` directory, add the following config:
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   output: {
     distPath: {
@@ -77,3 +83,13 @@ export default {
   },
 };
 ```
+
+The above config will generate the following directory structure:
+
+```bash
+build
+├── resource
+│   └── js
+│       └── index.js
+└── index.html
+```
diff --git a/website/docs/en/config/output/filename.mdx b/website/docs/en/config/output/filename.mdx
@@ -43,11 +43,15 @@ const prodDefaultFilename = {
 };
 ```
 
-Sets the filename of dist files.
+Sets the filename of output files.
 
 After the production build, Rsbuild will add a hash in the middle of the filename by default. If you don't need to add it, you can set [output.filenameHash](/config/output/filename-hash) to `false` to disable this behavior.
 
-The following are the details of each filename:
+## File types
+
+`output.filename` can be set differently for different file types.
+
+Here are the details of each `output.filename` option:
 
 - `html`: The name of the HTML files.
 - `js`: The name of the JavaScript files.
@@ -58,7 +62,7 @@ The following are the details of each filename:
 - `media`: The name of media assets, such as video.
 - `assets`: The name of other static assets. Such as the assets defined in [Extend Asset Types](/guide/basic/static-assets#extend-asset-types).
 
-> See [Output Files](/guide/basic/output-files) for more information.
+> See [Output files](/guide/basic/output-files) for more information.
 
 ## Example
 
diff --git a/website/docs/en/guide/basic/output-files.mdx b/website/docs/en/guide/basic/output-files.mdx
@@ -97,7 +97,7 @@ export default {
 };
 ```
 
-The above config produces the following directory structure:
+The above config will generate the following directory structure:
 
 ```bash
 dist
@@ -161,7 +161,7 @@ export default {
 };
 ```
 
-The above config produces the following directory structure:
+The above config will generate the following directory structure:
 
 ```bash
 dist
diff --git a/website/docs/zh/config/output/dist-path.mdx b/website/docs/zh/config/output/dist-path.mdx
@@ -25,8 +25,8 @@ type DistPathConfig = {
 const defaultDistPath = {
   root: 'dist',
   html: './',
-  js: isServer ? '' : 'static/js',
-  jsAsync: isServer ? '' : 'static/js/async',
+  js: output.target === 'node' ? '' : 'static/js',
+  jsAsync: output.target === 'node' ? '' : 'static/js/async',
   css: 'static/css',
   cssAsync: 'static/css/async',
   svg: 'static/svg',
@@ -38,36 +38,42 @@ const defaultDistPath = {
 };
 ```
 
-设置构建产物的输出目录，Rsbuild 会根据产物的类型输出到对应的子目录下。
-
-其中：
-
-- `root`: 表示所有构建产物输出的根目录。
-- `html`：表示 HTML 文件的输出目录。
-- `js`：表示 JavaScript 文件的输出目录。
-- `jsAsync`：表示异步 JavaScript 文件的输出目录，默认会输出到 `distPath.js` 的 `async` 子目录。
-- `css`：表示 CSS 文件的输出目录。
-- `cssAsync`：表示异步 CSS 文件的输出目录，默认会输出到 `distPath.css` 的 `async` 子目录。
-- `svg`：表示 SVG 图片的输出目录。
-- `font`：表示字体文件的输出目录。
-- `wasm`：表示 WebAssembly 文件的输出目录。
-- `image`：表示非 SVG 图片的输出目录。
-- `media`：表示视频等媒体资源的输出目录。
+设置构建产物的输出目录，Rsbuild 会根据产物的类型将其输出到相应的子目录中。
+
+> 查看 [构建产物目录](/guide/basic/output-files) 了解更多。
+
+## 文件类型
+
+`output.distPath` 可以为不同类型的文件设置不同的输出目录。
+
+下面是 `output.distPath` 中各个选项的说明：
+
+- `root`: 所有构建产物输出的根目录。
+- `html`：HTML 文件的输出目录。
+- `js`：JavaScript 文件的输出目录。
+- `jsAsync`：异步 JavaScript 文件的输出目录，默认会输出到 `distPath.js` 的 `async` 子目录。
+- `css`：CSS 文件的输出目录。
+- `cssAsync`：异步 CSS 文件的输出目录，默认会输出到 `distPath.css` 的 `async` 子目录。
+- `svg`：SVG 图片的输出目录。
+- `font`：字体文件的输出目录。
+- `wasm`：WebAssembly 文件的输出目录。
+- `image`：非 SVG 图片的输出目录。
+- `media`：视频等媒体资源的输出目录。
 - `assets`：其他静态资源的输出目录。例如 [扩展静态资源类型](/guide/basic/static-assets#扩展静态资源类型) 中定义的资源。
 
-### 根目录
+## 根目录
 
 `root` 是构建产物的根目录，可以为相对路径或绝对路径。如果 `root` 的值为相对路径，则会基于当前项目的根目录拼接为绝对路径。
 
 其他目录只能为相对路径，并且会相对于 `root` 进行输出。
 
-### 示例
+## 示例
 
 以 JavaScript 文件为例，会输出到 `distPath.root` + `distPath.js` 目录，即为 `dist/static/js`。
 
 如果需要将 JavaScript 文件输出到 `build/resource/js` 目录，可以这样设置：
 
-```js
+```ts title="rsbuild.config.ts"
 export default {
   output: {
     distPath: {
@@ -77,3 +83,13 @@ export default {
   },
 };
 ```
+
+以上配置会生成如下的目录结构：
+
+```bash
+build
+├── resource
+│   └── js
+│       └── index.js
+└── index.html
+```
diff --git a/website/docs/zh/config/output/filename.mdx b/website/docs/zh/config/output/filename.mdx
@@ -47,15 +47,19 @@ const prodDefaultFilename = {
 
 在生产模式构建后，Rsbuild 会自动在文件名中间添加 hash 值，如果不需要添加，可以将 [output.filenameHash](/config/output/filename-hash) 设置为 `false` 来禁用该行为。
 
-下面是各个文件类型的说明：
-
-- `html`：表示 HTML 文件的名称。
-- `js`：表示 JavaScript 文件的名称。
-- `css`：表示 CSS 样式文件的名称。
-- `svg`：表示 SVG 图片的名称。
-- `font`：表示字体文件的名称。
-- `image`：表示非 SVG 图片的名称。
-- `media`：表示视频等媒体资源的名称。
+## 文件类型
+
+`output.filename` 可以为不同类型的文件设置不同的名称。
+
+下面是 `output.filename` 中各个选项的说明：
+
+- `html`：HTML 文件的名称。
+- `js`：JavaScript 文件的名称。
+- `css`：CSS 样式文件的名称。
+- `svg`：SVG 图片的名称。
+- `font`：字体文件的名称。
+- `image`：非 SVG 图片的名称。
+- `media`：视频等媒体资源的名称。
 - `assets`：其他静态资源的名称。例如 [扩展静态资源类型](/guide/basic/static-assets#扩展静态资源类型) 中定义的资源。
 
 > 查看 [构建产物目录](/guide/basic/output-files) 了解更多。
diff --git a/website/docs/zh/guide/basic/output-files.mdx b/website/docs/zh/guide/basic/output-files.mdx
@@ -97,7 +97,7 @@ export default {
 };
 ```
 
-上方的配置会生成以下目录结构：
+以上配置会生成如下的目录结构：
 
 ```bash
 dist
@@ -161,7 +161,7 @@ export default {
 };
 ```
 
-上方的配置会生成以下目录结构：
+以上配置会生成如下的目录结构：
 
 ```bash
 dist
