#server.publicDir

• 类型：

type PublicDirOptions = {
  name?: string;
  copyOnBuild?: boolean | 'auto';
  ignore?: string[];
  watch?: boolean;
};
type PublicDir = false | PublicDirOptions | PublicDirOptions[];

• 默认值：

const defaultValue = {
  name: 'public',
  copyOnBuild: 'auto',
  ignore: [],
  watch: false,
};

默认情况下，Rsbuild 会将 public 目录作为静态资源服务的文件夹，该目录中的文件可在 server.base 路径下访问（默认 /）。

相关文档：public 目录。

#选项

#name

• 类型： string
• 默认值： 'public'

public 目录名称。name 的值可以设置为相对路径或绝对路径，相对路径将会相对于项目根目录进行解析。

• 相对路径示例：

export default {
  server: {
    publicDir: {
      name: '../some-public',
    },
  },
};

• 绝对路径示例：

import path from 'node:path';

export default {
  server: {
    publicDir: {
      name: path.join(__dirname, '../some-public'),
    },
  },
};

#copyOnBuild

• 类型： boolean | 'auto'
• 默认值： 'auto'

在生产构建时，是否将文件从 public 目录复制到构建产物目录。

• true: 复制文件。
• false: 不复制文件。
• 'auto': 当 output.target 不是 'node' 时，会复制文件，否则不复制。

#禁用

比如关闭 copyOnBuild：

export default {
  server: {
    publicDir: {
      copyOnBuild: false,
    },
  },
};

需要注意的是，将 copyOnBuild 的值为 false 后，如果执行 rsbuild preview 进行生产环境预览，将无法访问对应的静态资源文件。

#Node target

默认情况下，当 output.target 为 'node' 时，Rsbuild 不会复制 public 目录下的文件。

你可以将 copyOnBuild 设置为 true 来为 node target 复制文件：

export default {
  output: {
    target: 'node',
  },
  server: {
    publicDir: {
      copyOnBuild: true,
    },
  },
};

#ignore

• 类型： string[]
• 默认值： []

用于在生产构建复制 public 目录时，指定需要忽略的文件或目录的 glob 匹配模式。

该选项只影响构建阶段的复制行为，不会影响开发服务器对静态文件的访问。

例如，在复制 public 目录时忽略 foo.js：

export default {
  server: {
    publicDir: {
      ignore: ['**/foo.js'],
    },
  },
};

#watch

• 类型： boolean
• 默认值： false

是否监听 public 目录，并在文件发生变化时重新加载页面。

设置 watch 为 true 后，开发服务器会监听指定公共目录下的文件变化，并在文件发生变化时重新加载页面：

export default {
  server: {
    publicDir: {
      watch: true,
    },
  },
};

需要注意的是，watch 选项仅在开发模式下有效。如果 dev.hmr 和 dev.liveReload 都设置为 false，则 watch 将被忽略。

#多目录

server.publicDir 可以配置为一个数组，这允许你将多个目录作为静态资源服务的文件夹：

export default {
  server: {
    publicDir: [
      {
        name: 'public',
      },
      {
        name: 'assets',
        watch: false,
      },
    ],
  },
};

#禁用

你可以将 publicDir 设置成 false 来禁用静态资源服务：

export default {
  server: {
    publicDir: false,
  },
};

#多环境

#目录配置

• 版本： >= 2.3.0

你可以在 environments 中为每个环境配置 server.publicDir。环境中未配置 publicDir 时，会继承全局的 server.publicDir；设置 publicDir: false 则禁用该环境的 public 目录。

export default {
  environments: {
    client: {},
    admin: {
      server: {
        publicDir: {
          name: 'public-admin',
        },
      },
    },
    worker: {
      server: {
        publicDir: false,
      },
    },
  },
};

在这个示例中，client 使用 public，admin 使用 public-admin，worker 不使用 public 目录。

开发时，所有环境共用一个开发服务器，各环境配置的 public 文件都可以通过它访问。在某个环境中设置 publicDir: false，不会影响其他环境的 public 文件访问。

#配置继承

环境中单独配置的 publicDir 会替换全局 publicDir。未填写的选项使用默认值。

export default {
  server: {
    publicDir: {
      name: 'assets',
    },
  },
  environments: {
    client: {
      server: {
        publicDir: {
          copyOnBuild: false,
        },
      },
    },
  },
};

这里 client 没有设置 name，所以使用默认目录 public。如果要使用 assets，需要在 client.server.publicDir 中同时设置 name: 'assets'。

全局 publicDir 为 false 时，环境也可以通过配置 publicDir 对象或数组来启用自己的 public 目录。

#构建行为

生产构建时，每个环境将自己的 public 文件复制到输出目录。copyOnBuild 决定是否复制，ignore 指定复制时排除的文件。

例如，两个 web 环境都使用默认的 publicDir 设置，public/logo.png 的复制位置如下：

如果目录列表、目录顺序或 copyOnBuild、ignore 设置不同，两个环境会分别复制到自己的输出目录，即使输出目录存在嵌套关系。

#版本历史