引用静态资源#

Rsbuild 支持在代码中引用图片、字体、音频、视频等类型的静态资源。

静态资源格式#

以下是 Rsbuild 默认支持的静态资源格式：

• 图片：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp。
• 字体：woff、woff2、eot、ttf、otf、ttc。
• 音频：mp3、wav、flac、aac、m4a、opus。
• 视频：mp4、webm、ogg、mov。

如果你需要引用其他格式的静态资源，请参考 扩展静态资源类型。

在 JS 文件中引用#

在 JS 文件中，可以直接通过 import 的方式引用相对路径下的静态资源：

// 引用 static 目录下的 logo.png 图片
import logo from './static/logo.png';

export default = () => <img src={logo} />;

也支持使用路径别名来引用：

import logo from '@/static/logo.png';

export default = () => <img src={logo} />;

在 CSS 文件中引用#

在 CSS 文件中，可以引用相对路径下的静态资源：

.logo {
  background-image: url('../static/logo.png');
}

也支持使用路径别名来引用：

.logo {
  background-image: url('@/static/logo.png');
}

引用结果#

引用静态资源的结果取决于文件体积：

• 当文件体积大于 4KiB 时，会返回一个 URL，同时文件会被输出到构建产物目录下。
• 当文件体积小于 4KiB 时，会自动被内联为 Base64 格式。

import largeImage from './static/largeImage.png';
import smallImage from './static/smallImage.png';

console.log(largeImage); // "/static/largeImage.6c12aba3.png"
console.log(smallImage); // "data:image/png;base64,iVBORw0KGgo..."

关于资源内联的更详细介绍，请参考 静态资源内联 章节。

构建产物#

当静态资源被引用后，会自动被输出到构建产物的目录下，你可以：

• 通过 output.filename 来修改产物的文件名。
• 通过 output.distPath 来修改产物的输出路径。

请阅读 构建产物目录 来了解更多细节。

URL 前缀#

引用静态资源后返回的 URL 中会自动包含路径前缀：

• 在开发环境下，通过 dev.assetPrefix 设置路径前缀。
• 在生产环境下，通过 output.assetPrefix 设置路径前缀。

比如将 output.assetPrefix 设置为 https://example.com：

import logo from './static/logo.png';

console.log(logo); // "https://example.com/static/logo.6c12aba3.png"

public 目录#

项目根目录下的 public 目录可以用于放置一些静态资源，这些资源不会被 Rsbuild 打包。

• 当你启动开发服务器时，这些资源会被托管在 / 根路径下。
• 当你执行生产环境构建时，这些资源会被拷贝到 dist 目录。

比如，你可以在 public 目录下放置 robots.txt、manifest.json 或 favicon.ico 等文件。

引用方式#

在 HTML 模板中，你可以通过以下方式来引用 public 目录下的文件，assetPrefix 对应静态资源的 URL 前缀。

<link rel="icon" href="<%= assetPrefix %>/favicon.ico" />

在 JavaScript 代码中，你可以通过 process.env.ASSET_PREFIX 来拼接 URL：

const faviconURL = `${process.env.ASSET_PREFIX}/favicon.ico`;

自定义行为#

Rsbuild 提供了 server.publicDir 选项，可以用于自定义 public 目录的名称和行为，也可以用于禁用 public 目录。

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

注意事项#

• 请避免在源代码中通过 import 来引用 public 目录下的文件，正确的方式是通过 URL 引用。
• 通过 URL 引用 public 目录中的资源时，请使用绝对路径，而不是相对路径。
• 在生产环境构建过程中，public 目录中的文件将会被拷贝到构建产物目录（默认为 dist）下，请注意不要和产物文件出现名称冲突。当 public 下的文件和产物重名时，构建产物具有更高的优先级，会覆盖 public 下的同名文件。这个功能可以通过将 server.publicDir.copyOnBuild 设置为 false 来禁用。

类型声明#

当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义：

此时你需要为静态资源添加类型声明文件，请在项目中创建 src/env.d.ts 文件，并添加相应的类型声明。

• 方法一：如果项目里安装了 @rsbuild/core 包，你可以直接引用 @rsbuild/core 提供的类型声明：

/// <reference types="@rsbuild/core/types" />

• 方法二：手动添加需要的类型声明：

// 以 png 图片为例
declare module '*.png' {
  const content: string;
  export default content;
}

添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 env.d.ts 所在的目录，使 TypeScript 能够正确识别类型定义。

扩展静态资源类型#

如果 Rsbuild 内置的静态资源类型不能满足你的需求，那么你可以通过 tools.rspack 来修改内置的 Rspack 配置，并扩展你需要的静态资源类型。

比如，你需要把 *.pdf 文件当做静态资源直接输出到产物目录，可以添加以下配置：

export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.pdf$/,
          // 将资源转换为单独的文件，并且导出产物地址
          type: 'asset/resource',
        },
      ]);
    },
  },
};

添加以上配置后，你就可以在代码里引用 *.pdf 文件了，比如：

import myFile from './static/myFile.pdf';

console.log(myFile); // "/static/myFile.6c12aba3.pdf"

关于 asset modules 的更多介绍，请参考 Rspack - Asset modules。

自定义规则#

在某些场景下，你可能需要跳过 Rsbuild 内置的静态资源处理规则，并添加一些自定义规则。

以 PNG 图片为例，你需要：

1. 通过 tools.bundlerChain 来修改内置的 Rspack 配置，通过 exclude 排除 .png 文件。
2. 通过 tools.rspack 来添加自定义的静态资源处理规则。

export default {
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.module
        // 通过 `CHAIN_ID.RULE.IMAGE` 来定位到内置的图片规则
        .rule(CHAIN_ID.RULE.IMAGE)
        .exclude.add(/\.png$/);
    },
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.png$/,
          // 添加一个自定义的 loader 来处理 png 图片
          loader: 'custom-png-loader',
        },
      ]);
    },
  },
};

图片格式#

在使用图片资源时，你可以根据下方表格中图片的优缺点以及适用场景，来选择合适的图片格式。