跳至主要内容

404 問題排查指南

問題描述​

執行 開啟文件管理系統-預覽模式.bat 後，瀏覽器顯示 404 錯誤。

可能原因​

1. 建置未成功完成​

檢查方法：

  • 查看批次檔執行時的輸出，確認是否有 [SUCCESS] Generated static files 訊息
  • 檢查 build/ 資料夾是否存在
  • 檢查 build/index.html 是否存在

解決方法：

# 手動執行建置
npm run build

# 檢查建置結果
dir build

2. 端口被占用​

檢查方法：

  • 確認是否有其他程式使用 3000 端口
  • 嘗試使用其他端口（如 3001）

解決方法：

# 停止所有 Node.js 進程
Get-Process -Name node -ErrorAction SilentlyContinue | Stop-Process -Force

# 或使用不同端口
npm run serve -- --port 3001

3. baseUrl 配置問題​

檢查方法：

  • 打開 docusaurus.config.js
  • 確認 baseUrl: '/' 設定正確

解決方法： 如果 baseUrl 不是 '/'，請改為：

baseUrl: '/',

4. 多語言路徑問題​

Docusaurus 的多語言功能會在 URL 前加上語言代碼（如 /zh-TW/ 或 /en/）。

解決方法：

  • 嘗試訪問：http://localhost:3000/zh-TW/
  • 嘗試訪問：http://localhost:3000/en/
  • 而不是：http://localhost:3000/

5. 伺服器啟動時間​

docusaurus serve 可能需要 10-30 秒才能完全啟動。

解決方法：

  • 等待伺服器完全啟動後再訪問
  • 查看終端機輸出，確認顯示 "Server started" 或類似訊息

替代方案​

如果 docusaurus serve 一直有問題，可以使用：

方案 1：使用 Python HTTP 伺服器​

# 確保已建置
npm run build

# 使用 Python 內建伺服器
cd build
python -m http.server 8000

然後訪問：http://localhost:8000/zh-TW/

方案 2：使用 http-server（需要安裝）​

# 安裝 http-server
npm install -g http-server

# 啟動伺服器
cd build
http-server -p 8000

方案 3：使用批次檔​

可以使用 Python HTTP 伺服器作為替代方案（需要先執行 npm run build）。

診斷步驟​

  1. 確認建置成功

    npm run build

    檢查輸出是否有錯誤

  2. 檢查 build 資料夾

    dir build

    確認 index.html 存在

  3. 檢查多語言資料夾

    dir build\zh-TW
    dir build\en

    確認語言資料夾存在

  4. 嘗試不同 URL

    • http://localhost:3000/
    • http://localhost:3000/zh-TW/
    • http://localhost:3000/en/
    • http://localhost:3000/zh-TW/docs/intro

  5. 檢查終端機輸出 查看是否有錯誤訊息或警告

如果問題仍然存在​

請提供以下資訊：

  1. 建置時的完整輸出（是否有錯誤）
  2. build/ 資料夾的內容列表
  3. 訪問的完整 URL
  4. 瀏覽器開發者工具（F12）的 Console 和 Network 分頁的錯誤訊息
  5. 終端機中 npm run serve 的完整輸出