#静态资源内联

静态资源内联是一种优化网页性能的方法，它指的是将静态资源直接内联到 HTML 或 JS 文件中，而不是使用外部文件引用的方式。这样做的好处是减少了浏览器发起的请求数，从而提高页面的加载速度。

不过，静态资源内联也有一些缺点，比如增加了单个文件的体积，可能会导致加载变慢。所以在实际应用中，需要根据具体情况来决定是否使用静态资源内联。

Rsbuild 默认内联体积不超过 4KiB 的静态资源。本节介绍如何调整阈值，以及如何对指定资源强制内联或禁用内联。

#自动内联

当图片、字体、媒体等文件的体积不超过阈值（默认为 4KiB）时，Rsbuild 会将其转换为 Base64 字符串并内联，无需单独发送 HTTP 请求。超过阈值的资源会输出为独立文件，通过单独的 HTTP 请求加载。

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

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

自动内联的体积阈值可以通过 output.dataUriLimit 配置项修改。例如，修改图片资源的阈值为 5000 字节，设置视频资源不内联：

export default {
  output: {
    dataUriLimit: {
      image: 5000,
      media: 0,
    },
  },
};

#强制内联

你可以通过在引入资源时添加 inline URL 参数来强制内联该资源，无论该资源的体积是否小于阈值。

import img from './foo.png?inline';

export default function Foo() {
  return <img src={img} />;
}

在上面这个例子中，foo.png 图片将始终被内联，无论该图片的大小是否大于阈值。

#从 CSS 文件中引用

当你在 CSS 文件中引用静态资源时，同样可以通过 inline 参数来强制内联资源。

.foo {
  background-image: url('./icon.png?inline');
}

#禁用内联

当你想要阻止资源被内联，并确保它们始终作为单独的文件加载（无论文件大小如何），你可以添加 url query 参数。

import img from './foo.png?url';

export default function Foo() {
  return <img src={img} />;
}

在上面这个例子中，foo.png 图片将始终通过单独的资源文件加载，无论该图片的大小是否小于阈值。

#从 CSS 文件中引用

当你在 CSS 文件中引用静态资源时，同样可以通过 url 参数来禁用资源内联。

.foo {
  background-image: url('./icon.png?url');
}

#内联 JS 文件

除了将静态资源文件内联到 JS 文件里，Rsbuild 也支持将 JS 文件内联到 HTML 文件中。

启用 output.inlineScripts 后，生产构建会将 HTML 中引用的脚本内联，并从输出目录中移除这些文件。异步 chunk 仍作为独立文件输出。

export default {
  output: {
    inlineScripts: true,
  },
};

#内联 CSS 文件

你也可以将 CSS 文件内联到 HTML 文件中。

启用 output.inlineStyles 后，生产构建会将 HTML 中引用的样式表内联，并从输出目录中移除这些文件。异步 chunk 加载的 CSS 仍作为独立文件输出。

export default {
  output: {
    inlineStyles: true,
  },
};

#类型声明

当你在 TypeScript 代码中使用 ?inline 和 ?url 等 URL 参数时，TypeScript 可能会提示该模块缺少类型定义：

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

此时你可以使用以下任一方法添加类型声明：

• 方法一：如果项目里安装了 @rsbuild/core 包，你可以在 tsconfig.json 中添加 @rsbuild/core 提供的 预设类型：

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

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

declare module '*?url' {
  const content: string;
  export default content;
}
declare module '*?inline' {
  const content: string;
  export default content;
}