#静态资源

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 为 'node' 时，Rslib 还支持在 JavaScript 文件中引入 Node.js addons。

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

#在 JavaScript 文件中引用

#import 引用

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

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

console.log(logo); // "/static/image/logo.png"

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

也可以使用路径别名来引用：

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

console.log(logo); // "/static/image/logo.png"

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

在 format 为 cjs 或 esm 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会在代码转换时将源文件转化为一个 JavaScript 文件和一个根据 output.distPath 输出的静态资源文件，并保留引用静态资源的 import 或 require 语句。

下面是一个使用示例，假设源码如下：

src/index.ts

src/assets/logo.svg

import logo from './assets/logo.svg';

console.log(logo);

会根据配置文件中的 产物结构 配置，输出如下产物：

bundle

bundleless

dist/index.mjs

dist/static/svg/logo.svg

import logo_namespaceObject from './static/svg/logo.svg';

console.log(logo_namespaceObject);

dist/index.mjs

dist/assets/logo.mjs

dist/static/svg/logo.svg

import logo from './assets/logo.mjs';

console.log(logo);

import logo_namespaceObject from '../static/svg/logo.svg';
export { logo_namespaceObject as default };

#new URL 引用

你可以通过 JavaScript 原生的 URL 和 import.meta.url 相配合，来引用静态资源：

const logo = new URL('./assets/logo.svg', import.meta.url);

构建后，new URL() 中的路径会指向构建产物中的资源文件，并输出如下产物：

dist/index.js

dist/static/svg/logo.svg

const logo = new URL('./static/svg/logo.svg', import.meta.url);

通过 new URL() 引用的 .js、.ts、.css 和 .scss 等文件也会被视为 URL assets，不会经过相关的内置 loader 处理，其原始内容将作为资源输出。

export default {
  lib: [
    {
      bundle: false,
      source: {
        entry: {
          index: ['src/**', '!src/assets/logo.svg'],
        },
      },
    },
  ],
};

#跳过 new URL() 处理

如果不希望将项目源码中的 new URL() 解析为 URL asset，可以根据作用范围选择以下方式。

#关闭 URL parser

Rslib 默认会将内置 JavaScript rule 的 URL parser 设置为 'new-url-relative'。你可以通过 tools.bundlerChain 将该 rule 的 URL parser 设置为 false，来跳过项目源码中所有 new URL() 的资源解析：

import { defineConfig } from '@rslib/core';

export default defineConfig({
  tools: {
    bundlerChain(chain, { CHAIN_ID }) {
      chain.module
        .rule(CHAIN_ID.RULE.JS)
        .oneOf(CHAIN_ID.ONE_OF.JS_MAIN)
        .parser({
          url: false,
        });
    },
  },
});

关闭后，new URL() 表达式会原样保留，引用的文件不会由 Rslib 输出：

const logo = new URL('./assets/logo.svg', import.meta.url);

产物仍会保留标准的 new URL(path, import.meta.url) 形式。如果引用的资源需要随产物一起发布，建议通过 output.copy 等方式将其复制到产物目录，并确保输出路径与 new URL() 中的相对路径一致。这样无论产物由后续的打包工具继续处理，还是直接在 Node.js 中运行，都能正确定位该资源。

#忽略特定引用

如果只需要跳过某个 new URL() 的处理，可以在第一个参数前添加 rspackIgnore 注释：

const logo = new URL(
  /* rspackIgnore: true */ './assets/logo.svg',
  import.meta.url,
);

此时，Rslib 会使用运行时变量作为 new URL() 的基准 URL，产物中的表达式将不再保留 import.meta.url，这会限制后续打包工具在二次消费产物时对该资源引用的静态分析。

#在 CSS 文件中引用

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

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

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

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

在 format 为 cjs 或 esm 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 output.assetPrefix 设置为 "auto" 来使 CSS 产物中保留相对引用路径。

下面是一个使用示例，假设源码如下：

src/index.css

src/assets/logo.png

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

会输出如下产物：

dist/index.css

dist/static/image/logo.png

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

#在 CSS 中忽略某些文件引用

如果需要在 CSS 文件中引用绝对路径下的静态资源：

@font-face {
  font-family: DingTalk;
  src: url('/image/font/foo.ttf');
}

默认情况下，Rslib 内置的 css-loader 会解析 url() 中的绝对路径并寻找指定的模块。如果你希望跳过绝对路径的解析，可以配置 tools.cssLoader 来过滤指定的路径，被过滤的路径将被原样保留在代码中。

export default {
  tools: {
    cssLoader: {
      url: {
        filter: (url) => {
          if (/\/image\/font/.test(url)) {
            return false;
          }
          return true;
        },
      },
    },
  },
};

#静态资源内联

在 format 为 cjs 或 esm 时，Rslib 将产物视为会被其他打包工具再次消费的中间产物，默认会将 output.dataUriLimit 设置为 0 以不内联任何静态资源。

#构建产物目录

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

• 通过 output.filename 来修改产物的文件名。例如，在产物的文件名中添加 hash 值，这通常在有同名文件时使用，以避免文件名冲突。

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 来修改产物的输出路径。例如，将静态资源产物输出到 dist/resource 目录下。

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 提供的 预设类型：

{
  "compilerOptions": {
    "types": ["@rslib/core/types"]
  }
}

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

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

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

#扩展静态资源类型

如果 Rslib 内置的静态资源类型不能满足你的需求，可以通过以下方式扩展额外的静态资源类型。

#使用 source.assetsInclude

通过 source.assetsInclude 配置项，你可以指定需要被视为静态资源的额外文件类型。

export default {
  source: {
    assetsInclude: /\.gltf$/,
  },
};

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

import myFile from './static/model.gltf';

console.log(myFile); // "/static/assets/model.gltf"

#使用 tools.rspack

可以通过 tools.rspack 来修改内置的 Rspack 配置，并添加自定义的静态资源处理规则。

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

export default {
  tools: {
    rspack(config, { addRules }) {
      addRules([
        {
          test: /\.gltf$/,
          // 将资源转换为单独的文件，并且保留 import 语句
          type: 'asset/resource',
          generator: {
            importMode: 'preserve',
          },
        },
      ]);
    },
  },
};

关于资源模块的更多介绍，请参考 Rspack - 资源模块。