Skip to main content
Version: 3.7.0

静态资源

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

默认情况下，建议您将这些资源放在static文件夹中。您放入该目录的每个文件都将被复制到生成的build文件夹的根目录中，并保留目录层次结构。例如，如果您将一个名为sun.jpg的文件添加到静态文件夹中，它将被复制到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'],
  // ...
};

现在，public 和 static 中的所有文件都将被复制到构建输出中。

引用您的静态资源​

在 JSX 中​

在JSX中，你可以使用绝对URL从static文件夹中引用资源，但这并不理想，因为更改站点的baseUrl会破坏这些链接。对于在https://example.com/test提供的图片，浏览器会尝试从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>
use Markdown syntax

Docusaurus 只会解析 Markdown 语法中的链接。如果你的资源引用使用的是 JSX 标签 / ，则不会进行任何处理。

在 CSS 中​

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

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

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

important takeaway

一个重要的要点：永远不要硬编码你的基础URL！ 基础URL被视为实现细节，应该易于更改。所有路径，即使它们看起来像URL段，实际上都是文件路径。

如果你觉得URL段心理模型更容易理解，这里有一个经验法则：

  • 在编写JSX时，假装你有一个像/test/这样的基础URL，这样你就不会使用像src="/img/thumbnail.png"这样的绝对URL路径，而是使用require来加载资源。
  • 在编写Markdown或CSS时，假装它是/，这样你总是使用不带基础URL的绝对路径。

注意事项​

请记住：

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