跳到主要内容

静态资源

每个网站都需要静态资源:图片、样式表、网站图标(favicon)等。在这种情况下,您可以在项目的根目录下创建一个名为 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 网络路径进行访问。

引用静态资源#

你可以在代码中使用绝对路径来引用 static 文件夹中的资源,但这并不理想,因为更改站点的 baseUrl破坏这些链接

推荐使用 import / require() 来引用静态资源,或者使用 useBaseUrl 工具函数:两种方式都能将 baseUrl 添加到路径前。

JSX 示例#

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')} />;

你还可以导入(import) SVG 图片,这些图片将被转换为 React 组件。

MyComponent.js
import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

Markdown 示例#

Markdown links and images referencing assets of the static folder will be converted to require("@site/static/assetName.png")", and the site baseUrl will be automatically prepended for you.

my-doc.md
![Docusaurus](/img/docusaurus.png)

幸亏有了 MDX,您还可以在 Markdown 文件中使用 useBaseUrl 工具函数!不过,您必须使用 html 的 <img> 标签,而不是 Markdown 的图片语法。并且该语法与 JSX 语法完全相同。

my-doc.mdx
---
id: my-doc
title: My Doc
---
// Add to the top of the file below the front matter.
import useBaseUrl from '@docusaurus/useBaseUrl';
...
<img alt="Docusaurus with Keytar" src={useBaseUrl('/img/docusaurus_keytar.svg')} />

注意事项#

请记住:

  • 默认情况下,static 目录中的所有文件均不会进行后期处理或压缩。
  • 以绝对路径引用的文件在编译时不做检测,因此一旦文件丢失就会导致 404 错误。
  • 默认情况下,GitHub Pages 使用 Jekyll 来运行托管的网站。由于 Jekyll 会丢弃所有以 _ 字符开头的文件,因此,如果你使用 GitHub pages 托管你的网站,建议你通过将名为 .nojekyll 的空文件添加到 static 目录中来禁用 Jekyll。