> For AI agents: the complete documentation index is available at /zh/llms.txt, the full documentation bundle is available at /zh/llms-full.txt.
# 静态资源
Rslib 支持在代码中引用图片、字体、媒体和其他类型文件等静态资源。
## 静态资源格式
以下是 Rslib 默认支持的静态资源格式：
- **图片**：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tif、tiff、jfif、pjpeg、pjp、cur、jxl。
- **字体**：woff、woff2、eot、ttf、otf、ttc。
- **音频**：mp3、wav、flac、aac、m4a、opus。
- **视频**：mp4、webm、ogg、mov。
- **其他**：webmanifest、pdf、txt、vtt。
除上述静态资源格式外，当 [output.target](/zh/config/rsbuild/output.md#outputtarget) 为 `'node'` 时，Rslib 还支持在 JavaScript 文件中引入 Node.js [addons](https://nodejs.org/api/addons.html)。
如果你需要引用其他格式的静态资源，请参考 [扩展静态资源类型](#扩展静态资源类型)。
## 在 JavaScript 文件中引用
### `import` 引用
在 JavaScript 文件中，可以直接通过 `import` 的方式引用相对路径下的静态资源：
```tsx
// 引用 src/assets 目录下的 logo.png 图片
import logo from './assets/logo.png';
console.log(logo); // "/static/image/logo.png"
export default () => 
;
```
也可以使用**路径别名**来引用：
```tsx
import logo from '@/assets/logo.png';
console.log(logo); // "/static/image/logo.png"
export default () => ;
```
在 [format](/zh/config/lib/format.md) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会在代码转换时将源文件转化为一个 JavaScript 文件和一个根据 [output.distPath](/zh/config/rsbuild/output.md#outputdistpath) 输出的静态资源文件，并保留引用静态资源的 `import` 或 `require` 语句。
下面是一个使用示例，假设源码如下：
**src/index.ts**
```tsx
import logo from './assets/logo.svg';
console.log(logo);
```
**src/assets/logo.svg**
会根据配置文件中的 [产物结构](/zh/guide/basic/output-structure.md) 配置，输出如下产物：
**bundle**
**dist/index.mjs**
```tsx
import logo_namespaceObject from './static/svg/logo.svg';
console.log(logo_namespaceObject);
```
**dist/static/svg/logo.svg**
**bundleless**
**dist/index.mjs**
```tsx
import logo from './assets/logo.mjs';
console.log(logo);
```
**dist/assets/logo.mjs**
```tsx
import logo_namespaceObject from '../static/svg/logo.svg';
export { logo_namespaceObject as default };
```
**dist/static/svg/logo.svg**
### `new URL` 引用
:::note
使用 `new URL()` 引用静态资源时，仅支持生成 ESM 格式的产物，因此 [format](/zh/config/lib/format.md) 必须设置为 `'esm'`（默认值）。
:::
你可以通过 JavaScript 原生的 [URL](https://developer.mozilla.org/zh-CN/docs/Web/API/URL/URL) 和 [import.meta.url](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Operators/import.meta) 相配合，来引用静态资源：
```ts title="src/index.ts"
const logo = new URL('./assets/logo.svg', import.meta.url);
```
构建后，`new URL()` 中的路径会指向构建产物中的资源文件，并输出如下产物：
**dist/index.js**
```js
const logo = new URL('./static/svg/logo.svg', import.meta.url);
```
**dist/static/svg/logo.svg**
通过 `new URL()` 引用的 `.js`、`.ts`、`.css` 和 `.scss` 等文件也会被视为 URL assets，不会经过相关的内置 loader 处理，其原始内容将作为资源输出。
:::note
当 [bundle](/zh/config/lib/bundle.md) 为 `false` 时，默认入口为 glob 模式 `src/**`，会同时匹配 `src` 下的静态资源文件。对于已经通过 `new URL()` 引用的资源，需要在 [source.entry](/zh/config/rsbuild/source.md#sourceentry) 中排除这些文件。
```ts title="rslib.config.ts"
export default {
lib: [
{
bundle: false,
source: {
entry: {
index: ['src/**', '!src/assets/logo.svg'],
},
},
},
],
};
```
:::
#### 跳过 `new URL()` 处理
如果不希望将 `new URL()` 解析为 URL asset，可以根据作用范围选择以下方式。
##### 关闭 URL parser
构建 ESM 产物时，Rslib 默认使用 URL parser 的 [`'new-url-relative'`](https://rspack.rs/zh/config/module-parser#javascripturl) 模式处理 JavaScript 和 TypeScript 文件中的 `new URL()` 表达式。
如果希望保留原始的 `new URL()` 表达式，且不由 Rslib 输出对应资源，可以通过 [tools.bundlerChain](/zh/config/rsbuild/tools.md#toolsbundlerchain) 将 URL parser 设置为 `false`：
```ts title="rslib.config.ts"
import { defineConfig } from '@rslib/core';
export default defineConfig({
tools: {
bundlerChain(chain) {
chain.module.rule('rslib:new-url').parser({
url: false,
});
},
},
});
```
关闭后，`new URL()` 表达式会原样保留，引用的文件不会由 Rslib 输出：
```js title="dist/index.js"
const logo = new URL('./assets/logo.svg', import.meta.url);
```
产物仍会保留标准的 `new URL(path, import.meta.url)` 形式。如果引用的资源需要随产物一起发布，建议通过 [output.copy](/zh/config/rsbuild/output.md#outputcopy) 等方式将其复制到产物目录，并确保输出路径与 `new URL()` 中的相对路径一致。这样无论产物由后续的打包工具继续处理，还是直接在 Node.js 中运行，都能正确定位该资源。
##### 忽略特定引用
如果只需要跳过某个 `new URL()` 表达式的处理，可以在第一个参数前添加 [rspackIgnore](https://rspack.rs/zh/api/runtime-api/module-methods#rspackignore) 注释。此时，产物中会保留标准的 `new URL(path, import.meta.url)` 表达式：
```ts title="src/index.ts"
const logo = new URL(
/* rspackIgnore: true */ './assets/logo.svg',
import.meta.url,
);
```
## 在 CSS 文件中引用
在 CSS 文件中，可以引用相对路径下的静态资源：
```css title="src/index.css"
.logo {
background-image: url('./assets/logo.png');
}
```
也支持使用**路径别名**来引用：
```css title="src/index.css"
.logo {
background-image: url('@/assets/logo.png');
}
```
在 [format](/zh/config/lib/format.md) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 [output.assetPrefix](/zh/config/rsbuild/output.md#outputassetprefix) 设置为 `"auto"` 来使 CSS 产物中保留相对引用路径。
下面是一个使用示例，假设源码如下：
**src/index.css**
```css
.logo {
background-image: url('./assets/logo.png');
}
```
**src/assets/logo.png**
会输出如下产物：
**dist/index.css**
```css
.logo {
background-image: url('./static/image/logo.png');
}
```
**dist/static/image/logo.png**
***
### 在 CSS 中忽略某些文件引用
如果需要在 CSS 文件中引用绝对路径下的静态资源：
```css
@font-face {
font-family: DingTalk;
src: url('/image/font/foo.ttf');
}
```
默认情况下，Rslib 内置的 `css-loader` 会解析 `url()` 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 [`tools.cssLoader`](/zh/config/rsbuild/tools.md#toolscssloader) 来过滤指定的路径，被过滤的路径将被原样保留在代码中。
```ts
export default {
tools: {
cssLoader: {
url: {
filter: (url) => {
if (/\/image\/font/.test(url)) {
return false;
}
return true;
},
},
},
},
};
```
## 静态资源内联
在 [format](/zh/config/lib/format.md) 为 `cjs` 或 `esm` 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 [output.dataUriLimit](/zh/config/rsbuild/output.md#outputdataurilimit) 设置为 `0` 以不内联任何静态资源。
## 构建产物目录
当静态资源被引用后，会自动被输出到构建产物的目录下，你可以：
- 通过 [output.filename](/zh/config/rsbuild/output.md#outputfilename) 来修改产物的文件名。例如，在产物的文件名中添加 hash 值，这通常在有同名文件时使用，以避免文件名冲突。
```ts title="rslib.config.ts"
export default {
output: {
filename: {
svg: '[name].[contenthash:10].svg',
font: '[name].[contenthash:10][ext]',
image: '[name].[contenthash:10][ext]',
media: '[name].[contenthash:10][ext]',
assets: '[name].[contenthash:10][ext]',
},
},
};
```
- 通过 [output.distPath](/zh/config/rsbuild/output.md#outputdistpath) 来修改产物的输出路径。例如，将静态资源产物输出到 `dist/resource` 目录下。
```ts title="rslib.config.ts"
export default {
output: {
distPath: {
svg: 'resource/svg',
font: 'resource/font',
image: 'resource/image',
media: 'resource/media',
assets: 'resource/assets',
},
},
};
```
## 类型声明
当你在 TypeScript 代码中引用静态资源时，TypeScript 可能会提示该模块缺少类型定义：
```
TS2307: Cannot find module './logo.png' or its corresponding type declarations.
```
此时你可以使用以下任一方法添加类型声明：
- 方法一：如果项目里安装了 `@rslib/core` 包，你可以在 `tsconfig.json` 中添加 `@rslib/core` 提供的 [预设类型](/zh/guide/basic/typescript.md#预设类型)：
```json title="tsconfig.json"
{
"compilerOptions": {
"types": ["@rslib/core/types"]
}
}
```
- 方法二：手动添加需要的类型声明：
```ts title="src/env.d.ts"
// 以 png 图片为例
declare module '*.png' {
const url: string;
export default url;
}
```
添加类型声明后，如果依然存在上述错误提示，请尝试重启当前 IDE，或者调整 `env.d.ts` 所在的目录，使 TypeScript 能够正确识别类型定义。
## 扩展静态资源类型
如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。
### 使用 `source.assetsInclude`
通过 [source.assetsInclude](/zh/config/rsbuild/source.md#sourceassetsinclude) 配置项，你可以指定需要被视为静态资源的额外文件类型。
```ts title="rslib.config.ts"
export default {
source: {
assetsInclude: /\.gltf$/,
},
};
```
添加以上配置后，你就可以在代码里引用 `*.gltf` 文件了，比如：
```js
import myFile from './static/model.gltf';
console.log(myFile); // "/static/assets/model.gltf"
```
### 使用 `tools.rspack`
可以通过 [tools.rspack](/zh/config/rsbuild/tools.md#toolsrspack) 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。
比如，把 `*.gltf` 文件当做静态资源输出到产物目录，可以添加以下配置：
```ts title="rslib.config.ts"
export default {
tools: {
rspack(config, { addRules }) {
addRules([
{
test: /\.gltf$/,
// 将资源转换为单独的文件，并且保留 import 语句
type: 'asset/resource',
generator: {
importMode: 'preserve',
},
},
]);
},
},
};
```
关于资源模块的更多介绍，请参考 [Rspack - 资源模块](https://rspack.rs/zh/guide/features/asset-module)。