feat: allow publicDir.copyOnBuild to be 'auto' (#4299)

packages/core/src/config.ts

@@ -679,18 +679,16 @@ export function stringifyConfig(config: unknown, verbose?: boolean): string {
   return stringify(config, { verbose });
 }
 
-type NormalizePublicDirOptions = PublicDirOptions &
-  Required<Omit<PublicDirOptions, 'copyOnBuild'>>;
-
 export const normalizePublicDirs = (
   publicDir?: PublicDir,
-): NormalizePublicDirOptions[] => {
+): Required<PublicDirOptions>[] => {
   if (publicDir === false) {
     return [];
   }
 
-  const defaultConfig: NormalizePublicDirOptions = {
+  const defaultConfig: Required<PublicDirOptions> = {
     name: 'public',
+    copyOnBuild: 'auto',
     watch: false,
   };
 

packages/core/src/plugins/server.ts

@@ -49,9 +49,11 @@ export const pluginServer = (): RsbuildPlugin => ({
         const distPaths = dedupeNestedPaths(
           Object.values(environments)
             .filter(
-              (e) => copyOnBuild === true || e.config.output.target !== 'node',
+              ({ config }) =>
+                copyOnBuild === true ||
+                (copyOnBuild === 'auto' && config.output.target !== 'node'),
             )
-            .map((e) => e.distPath),
+            .map(({ distPath }) => distPath),
         );
 
         try {

packages/core/src/types/config.ts

@@ -321,10 +321,13 @@ export type PublicDirOptions = {
    */
   name?: string;
   /**
-   * Whether to copy files from the publicDir to the distDir on production build
-   * @default target !== 'node'
+   * Whether to copy files from the public directory to the dist directory on production build.
+   * - `true`: copy files
+   * - `false`: do not copy files
+   * - `'auto'`: if `output.target` is not `'node'`, copy files, otherwise do not copy
+   * @default 'auto'
    */
-  copyOnBuild?: boolean;
+  copyOnBuild?: boolean | 'auto';
   /**
    * whether to watch the public directory and reload the page when the files change
    * @default false

website/docs/en/config/server/public-dir.mdx

@@ -5,7 +5,7 @@
 ```ts
 type PublicDirOptions = {
   name?: string;
-  copyOnBuild?: boolean;
+  copyOnBuild?: boolean | 'auto';
   watch?: boolean;
 };
 type PublicDir = false | PublicDirOptions | PublicDirOptions[];
@@ -16,7 +16,8 @@ type PublicDir = false | PublicDirOptions | PublicDirOptions[];
 ```js
 const defaultValue = {
   name: 'public',
-  copyOnBuild: target !== 'node',
+  copyOnBuild: 'auto',
+  watch: false,
 };
 ```
 
@@ -61,10 +62,20 @@ export default {
 
 ### copyOnBuild
 
-- **Type:** `boolean`
-- **Default:** `target !== 'node'`
+- **Type:** `boolean | 'auto'`
+- **Default:** `'auto'`
+
+Whether to copy files from the public directory to the dist directory on production build.
+
+- `true`: copy files.
+- `false`: do not copy files.
+- `'auto'`: if [output.target](/config/output/target) is not `'node'`, copy files, otherwise do not copy.
+
+:::tip
+During dev builds, if you need to copy some static assets to the output directory, you can use the [output.copy](/config/output/copy) option instead.
+:::
 
-Whether to copy files from the publicDir to the distDir on production build.
+#### Disable
 
 For example, disable `copyOnBuild`:
 
@@ -80,10 +91,17 @@ export default {
 
 Note that setting the value of `copyOnBuild` to false means that when you run `rsbuild preview` for a production preview, you will not be able to access the corresponding static resources.
 
-By default, the public directory is not copied in the node target environment. If you need to copy files from the public directory to the distDir in the node target environment, you can manually enable `copyOnBuild`:
+#### Node Target
+
+By default, when [output.target](/config/output/target) is `'node'`, Rsbuild will not copy files from the public directory.
+
+You can set `copyOnBuild` to `true` to copy files for the `node` target:
 
 ```ts
 export default {
+  output: {
+    target: 'node',
+  },
   server: {
     publicDir: {
       copyOnBuild: true,
@@ -92,10 +110,6 @@ export default {
 };
 ```
 
-:::tip
-During dev builds, if you need to copy some static assets to the output directory, you can use the [output.copy](/config/output/copy) option instead.
-:::
-
 #### Multiple environments
 
 When performing [multi-environment builds](/guide/advanced/environments), Rsbuild copies files from the public directory to the output directory of each environment. If there are nested output directories, files will only be copied to the root of the output directory. For example:

website/docs/zh/config/server/public-dir.mdx

@@ -5,7 +5,7 @@
 ```ts
 type PublicDirOptions = {
   name?: string;
-  copyOnBuild?: boolean;
+  copyOnBuild?: boolean | 'auto';
   watch?: boolean;
 };
 type PublicDir = false | PublicDirOptions | PublicDirOptions[];
@@ -16,7 +16,7 @@ type PublicDir = false | PublicDirOptions | PublicDirOptions[];
 ```js
 const defaultValue = {
   name: 'public',
-  copyOnBuild: target !== 'node',
+  copyOnBuild: 'auto',
   watch: false,
 };
 ```
@@ -62,11 +62,21 @@ export default {
 
 ### copyOnBuild
 
-- **类型：** `boolean`
-- **默认值：** `target !== 'node'`
+- **类型：** `boolean | 'auto'`
+- **默认值：** `'auto'`
 
 在生产构建时，是否将文件从 public 目录复制到构建产物目录。
 
+- `true`: 复制文件。
+- `false`: 不复制文件。
+- `'auto'`: 当 [output.target](/config/output/target) 不是 `'node'` 时，会复制文件，否则不复制。
+
+:::tip
+在 dev 构建时，如果你需要拷贝一些静态资源到构建产物目录，可以使用 [output.copy](/config/output/copy) 选项代替。
+:::
+
+#### 禁用
+
 比如关闭 `copyOnBuild`：
 
 ```ts
@@ -81,10 +91,17 @@ export default {
 
 需要注意的是，将 `copyOnBuild` 的值为 false 后，如果执行 `rsbuild preview` 进行生产环境预览，将无法访问对应的静态资源文件。
 
-默认情况下，node 环境下不会进行复制。如果你需要在 node 环境下将文件从 public 目录复制到构建产物目录，可手动开启 `copyOnBuild`：
+#### Node Target
+
+默认情况下，当 [output.target](/config/output/target) 为 `'node'` 时，Rsbuild 不会复制 public 目录下的文件。
+
+你可以将 `copyOnBuild` 设置为 `true` 来为 `node` target 复制文件：
 
 ```ts
 export default {
+  output: {
+    target: 'node',
+  },
   server: {
     publicDir: {
       copyOnBuild: true,
@@ -93,10 +110,6 @@ export default {
 };
 ```
 
-:::tip
-在 dev 构建时，如果你需要拷贝一些静态资源到构建产物目录，可以使用 [output.copy](/config/output/copy) 选项代替。
-:::
-
 #### 多环境
 
 当执行 [多环境构建](/guide/advanced/environments) 时，Rsbuild 会将文件从 public 目录拷贝到各个环境的输出目录下。如果输出目录存在嵌套的情况，则只会拷贝文件到输出目录的根目录下。例如：