Django 在 Zeabur 部屬時的大小寫敏感性問題與解決方案

更新日期： 2025 年 1 月 12 日

當你將 Django 專案 部屬到 Zeabur 伺服器時，可能會遇到以下錯誤訊息：

django.template.loaders.filesystem.Loader: /app/TEMPLATES/shared/layout.html (Source does not exist)

這個錯誤通常是由於檔案系統的大小寫敏感性所導致的。

本文將解釋這個問題的成因，並提供詳細的解決方法，讓你的 Django 專案能順利在 Zeabur 上運作。

Linux 的大小寫敏感性是什麼？

Linux 是 Zeabur 伺服器使用的作業系統之一，它對檔案與目錄名稱是 大小寫敏感（Case-sensitive）的。

這表示以下路徑在 Linux 上會被視為不同的檔案或資料夾：

• /app/templates/（小寫）✅ 正確的資料夾名稱
• /app/TEMPLATES/（大寫）❌ 不存在的資料夾

即使這兩個目錄名稱看起來相似，但 Linux 會將它們視為兩個完全不同的目錄。

為什麼會出錯？

在 Django 中，模板檔案（HTML Templates）是透過 settings.py 中的 TEMPLATES["DIRS"] 來指定路徑的。

如果這個設定檔中的目錄名稱，與實際檔案系統的名稱大小寫不符，Django 將無法找到模板檔案。

範例錯誤設定 (settings.py)

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "TEMPLATES"],  # 錯誤：使用了大寫
        "APP_DIRS": True,
    },
]

專案實際目錄結構

my_project/
├── templates/              <- 正確的小寫資料夾名稱
│   └── shared/
│       └── layout.html
├── manage.py
└── settings.py

結果：

• Django 會嘗試尋找 /app/TEMPLATES/shared/layout.html
• 但實際存在的目錄是 /app/templates/shared/layout.html
• 由於大小寫不符，導致 Source does not exist 錯誤

如何修正這個錯誤？

修正 settings.py 的模板路徑

請打開你的 settings.py，並將 TEMPLATES["DIRS"] 的目錄名稱修正為小寫，以符合實際專案結構。

修正範例 (settings.py)

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],  # 正確的小寫名稱
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.template.context_processors.debug",
                "django.template.context_processors.request",
                "django.contrib.auth.context_processors.auth",
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

修改目錄名稱

如果你的 settings.py 設定是正確的，但實際的檔案系統中使用了大寫目錄，你也可以直接將資料夾名稱更改為小寫。

使用終端機修正範例：

# 將目錄名稱修改為小寫
mv TEMPLATES templates

檢查目錄名稱

使用終端機指令檢查你的目錄名稱是否正確：

ls -l /app/

確認輸出的資料夾名稱為小寫 templates。

如何確認修正是否生效？

在本地測試

在終端機執行以下指令，測試模板是否能正常載入：

python manage.py runserver

在 Zeabur 重新部署

• 登入 Zeabur 控制台
• 重新部署專案
• 測試網站是否正常運作

總結與最佳實踐

1. 大小寫敏感性：Zeabur 使用的 Linux 伺服器是大小寫敏感的。
2. 正確設定：確保 settings.py 的 TEMPLATES["DIRS"] 使用小寫 templates。
3. 目錄檢查：使用終端機檢查實際的目錄名稱。
4. 快取清理：修正後建議清除快取並重新啟動伺服器。

完成這些步驟後，你的 Django 專案應該能夠順利部署並正常運作！