Docusaurus 常見問題排除
記錄在使用 Docusaurus 過程中遇到的常見問題和解決方案。
🎯 學習目標
- 了解 Docusaurus 常見的配置問題
- 掌握故障排除的基本方法
- 學會解讀錯誤訊息和日誌
- 建立問題解決的思維模式
🚨 Page Not Found 問題
問題描述
啟動 Docusaurus 開發服務器後,訪問網站出現 "Page Not Found" 錯誤,即使服務器顯示正常啟動。
常見原因
1. 路由配置問題
當使用 routeBasePath: '/'
將文檔設為根路徑時,需要正確配置首頁文檔。
錯誤配置:
// docusaurus.config.js
docs: {
routeBasePath: '/', // 將 docs 設為根路徑
}
<!-- docs/intro.md -->
---
sidebar_position: 1
---
# 歡迎頁面
正確配置:
// docusaurus.config.js
docs: {
routeBasePath: '/', // 將 docs 設為根路徑
}
<!-- docs/intro.md -->
---
sidebar_position: 1
slug: / # 🔑 關鍵:指定為根路徑
---
# 歡迎頁面
2. 頁面檔案衝突
如果同時存在 src/pages/index.js
和設定了 slug: /
的文檔,會產生路由衝突。
解決方案:
- 刪除或重新命名
src/pages/index.js
- 或者修改文檔的 slug 配置
3. 配置被註解
部分功能(如 blog)在配置中被註解掉,但導航連結仍然存在。
檢查項目:
// docusaurus.config.js
presets: [
[
'classic',
{
// ❌ 如果 blog 被註解,/blog 路由會 404
// blog: { ... },
// ✅ 確保啟用需要的功能
blog: {
showReadingTime: true,
// ...其他配置
},
},
],
],
診斷步驟
1. 檢查服務器狀態
npm start
確認看到:
[SUCCESS] Docusaurus website is running at: http://localhost:3000/
2. 檢查編譯錯誤
查看終端輸出是否有編譯錯誤或警告:
✔ Client
Compiled successfully in 1.36s
3. 檢查路由配置
- 確認
routeBasePath
設定 - 檢查首頁文檔的
slug
配置 - 驗證沒有路由衝突
4. 檢查檔案結構
docs/
├── intro.md # 需要有 slug: /
├── category-1/
│ └── page.md
└── category-2/
└── page.md
src/pages/
├── index.js.backup # 避免衝突,已備份
└── other-page.js
解決方案模板
步驟 1:檢查配置
// docusaurus.config.js
export default {
presets: [
[
'classic',
{
docs: {
sidebarPath: './sidebars.js',
routeBasePath: '/', // 如果要讓文檔作為首頁
},
blog: {
// 確保沒有被註解掉
showReadingTime: true,
},
},
],
],
};
步驟 2:設定首頁文檔
<!-- docs/intro.md -->
---
sidebar_position: 1
slug: / # 設定為根路徑
---
# 網站首頁
步驟 3:檢查頁面衝突
# 檢查是否有衝突的頁面文件
ls src/pages/index.*
# 如果存在,重新命名避免衝突
mv src/pages/index.js src/pages/index.js.backup
步驟 4:重啟服務器
# 停止現有服務器
Ctrl + C
# 重新啟動
npm start
🔍 其他常見問題
MDX 語法錯誤
問題: 文檔編譯失敗,出現 MDX 解析錯誤。
解決方案:
- 檢查 front matter 格式是否正確
- 確認 Markdown 語法無誤
- 檢查 JSX 組件語法
側邊欄不顯示
問題: 文檔存在但不在側邊欄中顯示。
檢查項目:
_category_.json
文件格式- 文檔的
sidebar_position
設定 sidebars.js
配置
圖片載入失敗
問題: 文檔中的圖片無法顯示。
解決方案:
- 圖片放在
static/img/
目錄 - 使用正確的相對路徑
- 檢查檔案名稱和副檔名
🛠️ 調試工具
瀏覽器開發者工具
- Network 面板:檢查 404 請求
- Console 面板:查看 JavaScript 錯誤
- Elements 面板:檢查路由是否正確載入
Docusaurus 調試
# 詳細輸出模式
DEBUG=true npm start
# 檢查建構輸出
npm run build
常用檢查指令
# 檢查依賴
npm ls
# 清除快取重新安裝
rm -rf node_modules package-lock.json
npm install
# 檢查配置語法
node -c docusaurus.config.js
📝 預防措施
開發最佳實踐
- 版本控制:每次重大變更前先提交
- 配置備份:保留可用的配置文件
- 分步測試:逐步修改並測試
- 文檔記錄:記錄自定義配置的原因
配置檢查清單
-
docusaurus.config.js
語法正確 - 路由配置無衝突
- 必要的功能已啟用
- Front matter 格式正確
- 檔案路徑和命名規範
- 依賴版本相容
🔗 相關資源
💡 經驗總結
- 問題定位:先確認服務器是否正常啟動
- 配置檢查:重點檢查路由相關配置
- 錯誤解讀:仔細閱讀終端輸出的錯誤訊息
- 逐步排除:從簡單配置開始,逐步添加複雜功能
- 文檔查詢:遇到問題先查閱官方文檔
記住:大多數 "Page Not Found" 問題都是配置問題,而不是程式碼錯誤。耐心檢查配置,問題通常很容易解決!🎯