静态资源

¥Static Assets

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

¥Static assets are the non-code files that are directly copied to the build output. They include images, stylesheets, favicons, fonts, etc.

默认情况下，建议你将这些资源放在 static 文件夹中。你放入该目录中的每个文件都将被复制到生成的 build 文件夹的根目录中，并保留目录层次结构。例如。如果你将名为 sun.jpg 的文件添加到静态文件夹中，它将被复制到 build/sun.jpg 中。

¥By default, you are suggested to put these assets in the static folder. Every file you put into that directory will be copied into the root of the generated build folder with the directory hierarchy preserved. E.g. if you add a file named sun.jpg to the static folder, it will be copied to build/sun.jpg.

这意味着：

¥This means that:

• 对于站点 baseUrl: '/'，图片 /static/img/docusaurus.png 将在 /img/docusaurus.png 提供。

  ¥for site baseUrl: '/', the image /static/img/docusaurus.png will be served at /img/docusaurus.png.

• 对于站点 baseUrl: '/subpath/'，图片 /static/img/docusaurus.png 将在 /subpath/img/docusaurus.png 提供。

  ¥for site baseUrl: '/subpath/', the image /static/img/docusaurus.png will be served at /subpath/img/docusaurus.png.

你可以在 docusaurus.config.js 中自定义静态目录源。例如，我们可以添加 public 作为另一个可能的路径：

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

docusaurus.config.js

export default {
  title: 'My site',
  staticDirectories: ['public', 'static'],
  // ...
};

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

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

引用你的静态资源

¥Referencing your static asset

在 JSX 中

¥In 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 处提供的。

¥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.

你可以对静态资源进行 import() 或 require()（推荐），或使用 useBaseUrl 实用函数：两者都将 baseUrl 添加到你的路径中。

¥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 组件。

¥You can also import SVG files: they will be transformed into React components.

MyComponent.js

import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';

<DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;

在 Markdown 中

¥In Markdown

在 Markdown 中，你可以在用 Markdown 语法编写链接或图片时坚持使用绝对路径，因为 Docusaurus 在解析 Markdown 时将它们作为 require 调用而不是 URL 处理。参见 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>

使用 Markdown 语法

Docusaurus 只会解析 Markdown 语法的链接。如果你的资源引用使用 JSX 标签 <a> / <img>，则不会执行任何操作。

¥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.

在 CSS 中

¥In CSS

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

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

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

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

重要的收获

一个重要的收获：永远不要对你的基本 URL 进行硬编码！基本 URL 被视为实现细节，并且应该可以轻松更改。所有路径，即使看起来像 URL 段，实际上都是文件路径。

¥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.

如果你发现 URL slug 心智模型更容易理解，请参考以下经验法则：

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

• 假设你在编写 JSX 时有一个像 /test/ 这样的基本 URL，这样你就不会使用像 src="/img/thumbnail.png" 这样的绝对 URL 路径，而是使用 require 资源。

  ¥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.

• 在编写 Markdown 或 CSS 时假装它是 /，这样你就始终使用不带基本 URL 的绝对路径。

  ¥Pretend it's / when writing Markdown or CSS so you always use absolute paths without the base URL.

注意事项

¥Caveats

请记住：

¥Keep in mind that:

• 默认情况下，static 文件夹中的任何文件都不会被后处理、散列或缩小。

  ¥By default, none of the files in the static folder will be post-processed, hashed, or minified.

  • 然而，正如我们上面所演示的，我们通常能够为你将它们转换为 require 调用，以便它们得到处理。这有利于积极的缓存和更好的用户体验。

    ¥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.

• 编译时不会检测到通过硬编码绝对路径引用的丢失文件，并会导致 404 错误。

  ¥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 页面进行托管，建议你通过将名为 .nojekyll 文件的空文件添加到 static 目录来禁用 Jekyll。

  ¥By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with _, it is recommended that you disable Jekyll by adding an empty file named .nojekyll file to your static directory if you are using GitHub pages for hosting.