Zeabur 根目錄 (Root Directory) 設定完整指南

在使用 Zeabur 部署 Django 專案時，正確設定 根目錄 (Root Directory) 是確保專案能順利執行的關鍵步驟之一。

這篇文章將為新手詳細解釋什麼是根目錄、如何正確設定，以及如何檢查設定是否正確，讓你可以順利完成網站的自動化部署。

什麼是「根目錄」？

根目錄 (Root Directory) 指的是你的專案程式碼中，作為主要執行入口的資料夾位置。Zeabur 會根據你設定的根目錄來尋找程式碼的主執行檔案，並從這裡開始進行部署與伺服器啟動。

根目錄的角色

• 定位到正確的程式碼位置
• 確保 Zeabur 能找到 manage.py 或其他執行檔
• 正確讀取依賴檔案，如 requirements.txt 或 pyproject.toml

Zeabur 根目錄的設定方式

在 Zeabur 平台上設定根目錄時，你需要告訴系統你的專案程式碼的主要入口位於哪個資料夾。

設定為 /（預設根目錄）

如果你的 Django 專案檔案結構如下：

my_project/
├── manage.py              <- Django 專案入口檔案
├── requirements.txt       <- Python 依賴安裝檔案
├── settings.py            <- Django 設定檔
├── app/                   <- Django 應用程式
└── .git/                  <- Git 儲存庫

這種情況下，manage.py 位於儲存庫的最上層 (root level)，根目錄設定為 / 即可。

Zeabur 會直接從專案的根層級尋找程式碼。

設定為自訂目錄

如果你的 Django 專案結構較為複雜，如下：

my_project/
├── backend/               <- Django 專案 (主要程式碼)
│   ├── manage.py
│   ├── requirements.txt
│   └── settings.py
├── frontend/              <- React 或 Vue 前端專案
│   └── package.json
└── .git/                  <- Git 儲存庫

這種情況下，由於 manage.py 位於 backend 資料夾內，因此你需要在 Zeabur 中將 根目錄設為 /backend，讓 Zeabur 正確找到 Django 專案的主要執行檔案。

如何檢查根目錄設定是否正確？

檢查根目錄是否包含必要檔案

在設定根目錄之前，請確認目錄內是否包含以下 Django 必備檔案：

• manage.py（Django 專案入口檔案）
• requirements.txt 或 pyproject.toml（Python 依賴檔案）
• settings.py（Django 設定檔案）

本地測試

在設定前，建議於本地端進行測試，以確認你的根目錄是否正確。

1. 開啟終端機 (Terminal)。
2. 導航到專案的根目錄，執行以下指令： python manage.py runserver
3. 如果 Django 專案正常啟動，表示根目錄正確無誤。

Zeabur 部署測試

1. 登入 Zeabur 控制台，選擇你的專案。
2. 進入服務設定，找到 根目錄 (Root Directory) 設定欄位。
3. 根據專案檔案結構，輸入 / 或 /backend。
4. 重新部署並檢查是否能正常啟動服務。

常見錯誤與解決方案

找不到 manage.py

錯誤訊息：

Error: Could not find 'manage.py'

解決方法：

• 檢查你的根目錄是否正確指向包含 manage.py 的資料夾。
• 如果 manage.py 在 /backend，請將根目錄設為 /backend。

缺少依賴檔案

錯誤訊息：

Error: Could not find 'requirements.txt'

解決方法：

• 確保你的 requirements.txt 檔案存在於根目錄下，或將其移動到正確的資料夾中。

專案啟動失敗

錯誤訊息：

Application failed to start

解決方法：

• 檢查 settings.py 中的資料庫設定是否正確。
• 確保在 Zeabur 上的環境變數正確設定。

總結與最佳實踐

什麼是根目錄？

• 根目錄是 Zeabur 尋找專案主要執行檔案（如 manage.py）的位置。

如何正確設定根目錄？

• 如果 manage.py 位於專案根層級，設定為 /。
• 如果 manage.py 位於子資料夾（如 /backend），請將根目錄設為 /backend。

如何檢查根目錄是否正確？

• 本地執行 python manage.py runserver 測試。
• 確保根目錄下包含 manage.py、requirements.txt 等必要檔案。

✅ 透過正確設定 Zeabur 的根目錄，你將能順利完成 Django 專案的自動化部署，並確保專案穩定運作。

現在就試試看吧！🚀