效能
Fumadocs MDX 的效能
概覽
Fumadocs MDX 是一個打包工具外掛,換句話說,它的效能上限較高,實際瓶頸取決於底層的打包工具。
以 Turbopack 和 Vite 等常見的打包工具來說,它足以應付擁有將近 500+ 個 MDX 檔案的大型文件網站,幾乎能滿足所有使用情境。
由於 Fumadocs MDX 與您的打包工具搭配運作,您可以在 MDX 檔案中匯入任何檔案,包括用戶端元件。 這帶來了極高的彈性,並確保所有內容預設都經過最佳化。
開發伺服器
分為兩種類型:
-
Lazy:Vite 等打包工具,以及 Node.js 和 Bun 等執行階段端的載入器,可以在請求模組時 (例如呼叫
await import()時) 按需編譯 MDX 檔案,因此開發伺服器的效能不太會受到 MDX 檔案數量影響。不過,請務必啟用延遲載入,延遲編譯才會生效。
-
Precompiled:Webpack 和 Turbopack 在開發模式下不支援延遲編譯,所有 MDX 檔案都必須事先編譯。視需要預先編譯的 MDX 檔案數量而定,開發伺服器可能會變慢。
雖然這是打包工具層級的限制,但如果您在意速度問題,我們建議改用本機 Markdown。它會略過打包工具層,在執行階段載入並編譯 MDX 檔案。詳情請參閱連結中的介紹。
圖片最佳化
Fumadocs MDX 會透過 Remark Image 將圖片解析為靜態匯入。 因此,圖片會依您所使用的 React 框架自動進行最佳化 (例如 Next.js Image API) 。

或放在 public 資料夾中
輸出結果:
import HelloImage from './hello.png';
<img alt="Hello" src={HelloImage} />
正式環境建置
在正式環境建置中,最耗時的部分通常是 TypeScript docgen (沒有 tsgo 時,TypeScript 編譯器相當緩慢) ,以及所有 MDX 檔案各自零碎的處理工作累加起來的開銷。
在沒有快取的情況下,大量 MDX 檔案可能會在建置期間造成極高的記憶體用量,原因如下:
- MDX 檔案編譯成 JavaScript 之後,打包工具還得再打包輸出的 JavaScript 檔案。
- 即使單一 MDX 檔案的編譯時間微不足道,累加起來仍可能相當可觀。例如約 2500 個檔案,假設每個檔案需要 25ms,冷建置最多將耗時 62.5 秒。
主要的解決方式是改為隨需編譯,讓內容只在收到請求時才載入。
本機 Markdown
如開發伺服器一節所建議,本機 Markdown 是不錯的替代方案:它完全在執行階段運作,不需要額外的編譯步驟。
遠端來源
建立自訂的內容來源,並以遠端方式載入內容。
如果您的內容來源不需要預先編譯內容檔案,便可透過 SSG 依需求處理這些檔案,進而提升建置速度。 不過,這樣就無法運用建置時期的最佳化 (例如打包) 。
如需實作自訂來源,請參閱自訂來源。
How is this guide?
