进阶 docusaurus.io 2026-10-13 10:58:59 · 23 阅读
第17章 静态资源管理
Version: 2.x 静态资源
静态资源指的是非代码文件，它们会被直接复制到构建输出中，包括图片、样式表、网站图标（favicon）、字体等。
默认情况下，建议你把这些资源放在 static 文件夹里。你放入该目录下的每个文件都会被复制到生成构建文件夹的根目录，且保持原有的目录层级结构。例如，如果你添加一个名为 sun.jpg 的文件到 static 文件夹，它会被复制到 build/sun.jpg。
这意味着：
- 对于 site baseUrl: '/'，图片 /static/img/docusaurus.png 会被提供在 /img/docusaurus.png。
- 对于 site baseUrl: '/subpath/'，图片 /static/img/docusaurus.png 会被提供在 /subpath/img/docusaurus.png。
你可以在 docusaurus.config.js 中自定义静态资源目录的来源。例如，我们可以添加 public 作为另一个可能的路径：
docusaurus.config.js
module.exports = {
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};
现在，public 和 static 中的所有文件都会被复制到构建输出中。 引用静态资源 在 JSX 中 在 JSX 中，你可以使用绝对 URL 来引用 static 文件夹中的资源，但这样做并不理想，因为更改 site baseUrl 会破坏这些链接。对于在 https://example.com/test 上提供的图片
，浏览器会尝试从 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';
;
MyComponent.js.default})
MyComponent.js import useBaseUrl from '@docusaurus/useBaseUrl';
})
;
你还可以导入 SVG 文件：它们会被转换成 React 组件。 MyComponent.js import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
在 Markdown 中使用 在 Markdown 里写链接或图片时，直接用绝对路径即可，因为 Docusaurus 解析 Markdown 时会把它们当作 require 调用而非 URL。详见 Markdown 静态资源。 你写成这样的链接：[下载本文档](/files/note.docx)
Docusaurus 会将其转换为：
仅限 Markdown 语法：Docusaurus 只会解析 Markdown 语法的链接。如果你的资源引用用的是 JSX 标签 /![]()
，则不会有任何处理。
在 CSS 中使用
在 CSS 中，通常用 url() 函数引用字体、图片等资源。引用静态资源时请使用绝对路径：
静态资源 static/font/Caroline.otf 会被打包器加载。 重要提示：千万不要硬编码 base URL！base URL 属于实现细节，应该可以随时修改。所有路径即使看起来像 URL slug，本质上也都是文件路径。 如果你觉得 URL slug 的心智模型更容易理解，可以遵循这条经验法则： 写 JSX 时，假设 base URL 是 /test/，这样你就不会用 src="/img/thumbnail.png" 这种绝对 URL 路径，而是用 require 引入资源。 写 Markdown 或 CSS 时，假设 base URL 是 /，这样始终使用不带 base URL 的绝对路径。 注意事项 请记住以下几点： 默认情况下，static 目录中的文件不会被后处理、哈希或压缩。 不过如上文所示，我们通常能把它们转换为 require 调用，从而纳入处理流程。这有利于激进缓存，带来更好的用户体验。 通过硬编码绝对路径引用的文件如果不存在，编译时不会报错，而是在运行时产生 404 错误。 默认情况下，GitHub Pages 会用 Jekyll 处理已发布的文件。由于 Jekyll 会丢弃所有以下划线 _ 开头的文件，如果你用 GitHub Pages 托管站点，建议在 static 目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。
title: 'My site',
staticDirectories: ['public', 'static'],
// ...
};
现在，public 和 static 中的所有文件都会被复制到构建输出中。 引用静态资源 在 JSX 中 在 JSX 中，你可以使用绝对 URL 来引用 static 文件夹中的资源，但这样做并不理想，因为更改 site baseUrl 会破坏这些链接。对于在 https://example.com/test 上提供的图片
，浏览器会尝试从 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';MyComponent.js
MyComponent.js import useBaseUrl from '@docusaurus/useBaseUrl';
;你还可以导入 SVG 文件：它们会被转换成 React 组件。 MyComponent.js import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
在 Markdown 中使用 在 Markdown 里写链接或图片时，直接用绝对路径即可，因为 Docusaurus 解析 Markdown 时会把它们当作 require 调用而非 URL。详见 Markdown 静态资源。 你写成这样的链接：
Docusaurus 会将其转换为：
下载本文档仅限 Markdown 语法：Docusaurus 只会解析 Markdown 语法的链接。如果你的资源引用用的是 JSX 标签 /
@font-face {
font-family: 'Caroline';
src: url('/font/Caroline.otf');
}静态资源 static/font/Caroline.otf 会被打包器加载。 重要提示：千万不要硬编码 base URL！base URL 属于实现细节，应该可以随时修改。所有路径即使看起来像 URL slug，本质上也都是文件路径。 如果你觉得 URL slug 的心智模型更容易理解，可以遵循这条经验法则： 写 JSX 时，假设 base URL 是 /test/，这样你就不会用 src="/img/thumbnail.png" 这种绝对 URL 路径，而是用 require 引入资源。 写 Markdown 或 CSS 时，假设 base URL 是 /，这样始终使用不带 base URL 的绝对路径。 注意事项 请记住以下几点： 默认情况下，static 目录中的文件不会被后处理、哈希或压缩。 不过如上文所示，我们通常能把它们转换为 require 调用，从而纳入处理流程。这有利于激进缓存，带来更好的用户体验。 通过硬编码绝对路径引用的文件如果不存在，编译时不会报错，而是在运行时产生 404 错误。 默认情况下，GitHub Pages 会用 Jekyll 处理已发布的文件。由于 Jekyll 会丢弃所有以下划线 _ 开头的文件，如果你用 GitHub Pages 托管站点，建议在 static 目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。
