静态资源
静态资源是直接复制到构建输出中的非代码文件。它们包括图像、样式表、网站图标、字体等。
默认情况下,建议您将这些资产放置在 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
作为另一个可能的路径
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
添加到路径前面。
示例
import DocusaurusImageUrl from '@site/static/img/docusaurus.png';
<img src={DocusaurusImageUrl} />;
<img src={require('@site/static/img/docusaurus.png').default} />
import useBaseUrl from '@docusaurus/useBaseUrl';
<img src={useBaseUrl('/img/docusaurus.png')} />;
您还可以导入 SVG 文件:它们将被转换为 React 组件。
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>
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。