靜態資產

靜態資源是直接複製到建置輸出的非程式碼檔案。它們包括圖像、樣式表、喜愛按鈕、字型等。

預設情況下，建議將這些資源放在 static 資料夾中。放入那個目錄中的每個檔案將被複製到已產生 build 資料夾的根目錄，並保留目錄階層。例如，如果你將一個名為 sun.jpg 的檔案新增到靜態資料夾，它將被複製到 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 作為可用的另一個路徑

docusaurus.config.js

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 路徑。

範例

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

在 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>

使用 Markdown 語法

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 段落)，實際上都是檔案路徑。

如果您認為 URL 段落心智模式較容易理解，請記住下列經驗法則

• 撰寫 JSX 時，請假設基本 URL 為 /test/，不要使用絕對 URL 路徑，例如 src="/img/thumbnail.png"，而是 require 資源。
• 撰寫 Markdown 或 CSS 時，請假設基本 URL 為 /，在沒有基本 URL 的情況下，請持續使用絕對路徑。

需注意

請牢記

• 預設情況下，static 資料夾中的所有檔案都不會進行後處理、雜湊或壓縮。
  • 然而，如我們上面展示的，我們通常可以將它們轉換成 require，這樣它們就會得到處理。這有助於積極快取和提升使用者體驗。
• 編譯時不會偵測到透過硬式編碼絕對路徑參考的遺失檔案，且會產生 404 錯誤。
• 預設情況下，GitHub Pages 透過 Jekyll，執行發佈的檔案。由於 Jekyll 會捨棄任何以 _ 開頭的檔案，建議如果你使用 GitHub Pages 作為 hosting 主機，請將一個檔案命名為 .nojekyll 的空檔案加入 static 目錄中，以停用 Jekyll。