跳到主要内容
版本:3.8.1

静态资源

静态资源是直接复制到构建输出中的非代码文件。它们包括图像、样式表、网站图标、字体等。

默认情况下,建议您将这些资产放置在 static 文件夹中。您放入该目录的每个文件都将被复制到生成的 build 文件夹的根目录中,并保留目录层次结构。例如,如果您将名为 sun.jpg 的文件添加到 static 文件夹中,它将被复制到 build/sun.jpg

这意味着

  • 对于网站 baseUrl: '/',图像 /static/img/docusaurus.png 将在 /img/docusaurus.png 提供。
  • 对于网站 baseUrl: '/subpath/',图像 /static/img/docusaurus.png 将在 /subpath/img/docusaurus.png 提供。

您可以在 docusaurus.config.js 中自定义静态目录源。例如,我们可以添加 public 作为另一个可能的路径

docusaurus.config.js
export default {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};

现在,publicstatic 中的所有文件都将被复制到构建输出中。

引用您的静态资源

在 JSX 中

在 JSX 中,您可以使用绝对 URL 在代码中引用 static 文件夹中的资源,但这并不理想,因为更改网站的 baseUrl 将会破坏这些链接。对于在 https://example.com/test 提供的图像 <img src="/img/docusaurus.png" />,浏览器将尝试从 URL 根目录解析它,即作为 https://example.com/img/docusaurus.png,这将失败,因为它实际上是在 https://example.com/test/img/docusaurus.png 提供的。

您可以 import()require() 静态资源(推荐),或者使用 useBaseUrl 实用函数:它们都会为您将 baseUrl 添加到路径前面。

示例

MyComponent.js
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';

<img src={DocusaurusImageUrl} />;
MyComponent.js
<img src={require('@site/static/img/docusaurus.png').default} />
MyComponent.js
import useBaseUrl from '@docusaurus/useBaseUrl';

<img src={useBaseUrl('/img/docusaurus.png')} />;

您还可以导入 SVG 文件:它们将被转换为 React 组件。

MyComponent.js
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';

<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

在 Markdown 中

在 Markdown 中,您可以在编写链接或图像时,在 Markdown 语法中坚持使用绝对路径,因为 Docusaurus 在解析 Markdown 时会将它们作为 require 调用而不是 URL 进行处理。请参阅Markdown 静态资源

You write a link like this: [Download this document](/files/note.docx)

Docusaurus changes that to: <a href={require('static/files/note.docx')}>Download this document</a>
使用 Markdown 语法

Docusaurus 只会解析 Markdown 语法中的链接。如果您的资源引用使用的是 JSX 标签 <a> / <img>,则不会进行任何操作。

在 CSS 中

在 CSS 中,url() 函数通常用于引用字体和图像等资源。要引用静态资源,请使用绝对路径

@font-face {
font-family: 'Caroline';
src: url('/font/Caroline.otf');
}

static/font/Caroline.otf 资产将由打包器加载。

重要提示

一个重要的提示是:永远不要硬编码您的基本 URL!基本 URL 被视为实现细节,应易于更改。所有路径,即使它们看起来像 URL slug,实际上都是文件路径。

如果您觉得 URL slug 的心智模型更容易理解,这里有一个经验法则

  • 在编写 JSX 时,假设您有一个基本 URL,例如 /test/,这样您就不会使用绝对 URL 路径,例如 src="/img/thumbnail.png",而是 require 该资产。
  • 在编写 Markdown 或 CSS 时,假设它是 /,这样您总是使用不带基本 URL 的绝对路径。

注意事项

请记住

  • 默认情况下,static 文件夹中的文件都不会进行后处理、哈希或缩小。
    • 然而,正如我们上面演示的,我们通常能够将它们转换为 require 调用,以便它们得到处理。这对于积极的缓存和更好的用户体验是有益的。
  • 在编译时,通过硬编码的绝对路径引用的缺失文件将不会被检测到,并会导致 404 错误。
  • 默认情况下,GitHub Pages 会通过 Jekyll 运行已发布的文件。由于 Jekyll 会丢弃任何以 _ 开头的文件,因此如果您使用 GitHub Pages 进行托管,建议您通过在 static 目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。