#引用静态资源

Modern.js 支持在代码中引用图片、字体、媒体类型的静态资源。

#静态资源格式

以下是 Modern.js 默认支持的静态资源格式：

• 图片：png、jpg、jpeg、gif、svg、bmp、webp、ico、apng、avif、tiff。
• 字体：woff、woff2、eot、ttf、otf、ttc。
• 媒体：mp4、webm、ogg、mp3、wav、flac、aac、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');
}

#引用结果

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

• 当文件体积大于 10KB 时，会返回一个 URL，同时文件会被输出到构建产物目录下。
• 当文件体积小于 10KB 时，会自动被内联为 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://modern.com：

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

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

#添加类型声明

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

TS2307: Cannot find module './logo.png' or its corresponding type declarations.

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

declare module '*.png' {
  const content: string;
  export default content;
}

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

#扩展静态资源类型

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

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

export default {
  tools: {
    bundlerChain(chain) {
      chain.module
        .rule('pdf')
        .test(/\.pdf$/)
        .type('asset/resource');
    },
  },
};

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

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

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

关于以上配置的更多介绍，请参考：

• Rspack 文档 - Asset modules
• webpack 文档 - Asset modules

#图片格式

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