跳到主要内容

静态资源

静态资源是指那些被直接复制到最终构建输出目录的非代码文件，如图片、样式表、网站图标、字体等。

默认情况下，我们建议您将这些资源放在 static 文件夹中。您放入该目录的每个文件都将被复制到生成的 build 文件夹的根目录，并保持原有的目录结构。例如，如果您在 static 文件夹中添加一个名为 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 上提供服务的网站，图片 <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 静态资源。

你这样写一个链接： [下载此文档](/files/note.docx)

道格龙（Docusaurus） 会将其转换为： <a href={require('static/files/note.docx')}>下载此文档</a>
请使用 Markdown 语法

道格龙（Docusaurus） 只会解析 Markdown 语法的链接。如果您的资源引用使用的是 JSX 标签 <a> / <img>，则不会进行任何处理。

在 CSS 中​

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

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

打包工具会加载 static/font/Caroline.otf 这个资源。

重要提示

一个重要的原则是：永远不要硬编码您的 base URL！ base URL 应被视为实现细节，并应能轻松更改。所有路径，即使它们看起来像 URL slugs，实际上都是文件路径。

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

  • 在编写 JSX 时，假定您的 base URL 是 /test/，这样您就不会使用像 src="/img/thumbnail.png" 这样的绝对 URL 路径，而是会通过 require 来引用资源。
  • 在编写 Markdown 或 CSS 时，假定它是 /，这样您就可以始终使用不带 base URL 的绝对路径。

注意事项​

请记住：

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