跳转至主内容
Version: 2.0.0-beta.21 🚧

静态资源

Every website needs assets: images, stylesheets, favicons, etc. By default, you are suggested to put these assets in the static folder.

放入此文件夹中的每个文件将自动复制进生成的 build 文件夹的根目录,同时保留其目录结构。 举个例子, 若您向 static 文件夹添加了 sun.jpg 文件,则其将会被复制到 build/sun.jpg 下。

这意味着:

  • 若设置 baseUrl: '/',则图像 /static/img/docusaurus.png 将位于 /img/docusaurus.png 处;
  • 若设置 baseUrl: '/子目录/',则图像 /static/img/docusaurus.png 将位于 /子目录/img/docusaurus.png 处。

You can customize the static directory sources in docusaurus.config.js. For example, we can add public as another possible path:

docusaurus.config.js
module.exports = {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};

Now, all files in public as well as static will be copied to the build output.

引用您的静态资源

In JSX

In JSX, you can reference assets from the static folder in your code using absolute URLs, but this is not ideal because changing the site baseUrl will break those links. For the image <img src="/img/docusaurus.png" /> served at https://example.com/test, the browser will try to resolve it from the URL root, i.e. as https://example.com/img/docusaurus.png, which will fail because it's actually served at https://example.com/test/img/docusaurus.png.

You can import() or require() the static asset (recommended), or use the useBaseUrl utility function: both prepend the baseUrl to paths for you.

Examples:

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" />;

In Markdown

In Markdown, you can stick to using absolute paths when writing links or images in Markdown syntax because Docusaurus handles them as require calls instead of URLs when parsing the Markdown. See Markdown static assets.

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 will only parse links that are in Markdown syntax. If your asset references are using the JSX tag <a> / <img>, nothing will be done.

In CSS

In CSS, the url() function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:

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

The static/font/Caroline.otf asset will be loaded by the bundler.

important takeaway

One important takeaway: never hardcode your base URL! The base URL is considered an implementation detail and should be easily changeable. All paths, even when they look like URL slugs, are actually file paths.

If you find the URL slug mental model more understandable, here's a rule of thumb:

  • Pretend you have a base URL like /test/ when writing JSX so you don't use an absolute URL path like src="/img/thumbnail.png" but instead require the asset.
  • Pretend it's / when writing Markdown or CSS so you always use absolute paths without the base URL.

提醒

有几点需要留意:

  • By default, none of the files in the static folder will be post-processed, hashed, or minified.
    • However, as we've demonstrated above, we are usually able to convert them to require calls for you so they do get processed. This is good for aggressive caching and better user experience.
  • Missing files referenced via hard-coded absolute paths will not be detected at compilation time and will result in a 404 error.
  • 默认情况下,GitHub Pages 通过 Jekyll 运行已发布的文件。 由于 Jekyll 忽略任意以 _ 开头的文件,所以若您使用 GitHub Pages,我们推荐您在 static 文件夹中新建 .nojekyll 文件来禁用 Jekyll。