close
  • 简体中文

      • dev.assetPrefix

      • 类型： boolean | string | 'auto'
      • 默认值： server.base

      设置 开发模式 下的静态资源 URL 前缀。

      assetPrefix 会影响构建产物中绝大部分静态资源的 URL，包括 JavaScript 文件、CSS 文件、图片、视频等。如果指定了一个错误的值，则在加载这些资源时可能会出现 404 错误。

      该配置项仅用于 development 模式。在 production 模式或 none 模式下，请使用 output.assetPrefix 配置项进行设置。

      默认值

      dev.assetPrefix 的默认值与 server.base 相同。

      当 server.base 为 /foo 时，可通过 http://localhost:3000/foo/ 访问到 index.html 及其他静态资源产物。

      需要注意的是，当自定义 dev.assetPrefix 选项时，如果希望静态资源能够通过 Rsbuild 开发服务器正常访问到，dev.assetPrefix 应和 server.base 包含相同的 URL 前缀，如：

      rsbuild.config.ts
      export default {
  dev: {
    assetPrefix: '/foo/bar/',
  },
  server: {
    base: '/foo',
  },
};

      Boolean 类型

      如果设置 assetPrefix 为 true，Rsbuild 会使用 http://localhost:<port>/ 作为 URL 前缀：

      rsbuild.config.ts
      export default {
  dev: {
    assetPrefix: true,
  },
};

      在浏览器中加载的资源 URL 如下：

      <script defer src="http://localhost:3000/static/js/main.js"></script>

      如果设置 assetPrefix 为 false 或不设置，则默认使用 / 作为访问前缀。

      String 类型

      当 assetPrefix 的值为 string 类型时，字符串会作为前缀，自动拼接到静态资源访问 URL 上。

      • 比如设置为相对于根目录的路径：
      rsbuild.config.ts
      export default {
  dev: {
    assetPrefix: '/example/',
  },
};

      在浏览器中加载的资源 URL 如下：

      <script defer src="http://localhost:3000/example/static/js/index.js"></script>
      • 比如设置为完整 URL：
      rsbuild.config.ts
      export default {
  dev: {
    assetPrefix: 'https://example.com/assets/',
  },
};

      在浏览器中加载的资源 URL 如下：

      <script defer src="https://example.com/assets/static/js/index.js"></script>

      端口号占位符

      Rsbuild server 监听的端口号可能会发生变更。比如，当端口被占用时，Rsbuild 会自动递增端口号，直至找到一个可用端口。

      为了避免端口变化导致 dev.assetPrefix 失效，你可以使用以下方法之一：

      • 开启 server.strictPort。
      • 使用 <port> 占位符来指代当前端口号，Rsbuild 会将占位符替换为实际监听的端口号。
      rsbuild.config.ts
      export default {
  dev: {
    assetPrefix: 'http://localhost:<port>/',
  },
};

      路径类型

      assetPrefix 可以设置为以下类型的路径：

      • 绝对路径：这是最常见的做法，可以为指定服务器路径，比如 /assets/。
      • 'auto'：Rspack 将自动计算路径，并生成基于文件所在位置的相对路径。
      Tip

      不建议将 assetPrefix 设置为相对路径，比如 './assets/'。因为当资源位于不同的路径深度时，使用相对路径可能会导致资源无法正确加载。

      对比 publicPath

      dev.assetPrefix 的功能与 Rspack 的 output.publicPath 配置基本一致。

      它与原生配置的区别在于：

      • dev.assetPrefix 仅在开发模式下生效。
      • dev.assetPrefix 默认值与 server.base 相同。
      • dev.assetPrefix 默认会自动补全尾部的 /。
      • dev.assetPrefix 的值会写入 process.env.ASSET_PREFIX 环境变量（只能在 client 代码中访问）。

      动态 asset prefix

      使用 Rspack 提供的 import.meta.rspackPublicPath 变量，可以在 JavaScript 代码中动态设置静态资源 URL 的前缀。

      详见 Rspack - 动态设置 publicPath。