如何管理靜態檔案（例如圖片、JavaScript、CSS）

網站通常需要提供額外的檔案，例如圖片、JavaScript 或 CSS。在 Django 中，我們將這些檔案稱為「靜態檔案」。Django 提供了 django.contrib.staticfiles 來幫助您管理它們。

此頁面說明如何提供這些靜態檔案。

設定靜態檔案

  1. 請確保 django.contrib.staticfiles 已包含在您的 INSTALLED_APPS 中。

  2. 在您的設定檔中，定義 STATIC_URL，例如

    STATIC_URL = "static/"

  3. 在您的模板中，使用 static 模板標籤，以使用已設定的 staticfiles STORAGES 別名來建構給定相對路徑的 URL。

    {% load static %}
<img src="{% static 'my_app/example.jpg' %}" alt="My image">

  4. 將您的靜態檔案儲存在應用程式中名為 static 的資料夾中。例如 my_app/static/my_app/example.jpg。

提供檔案

除了這些設定步驟之外，您還需要實際提供靜態檔案。

在開發期間，如果您使用 django.contrib.staticfiles，當 DEBUG 設定為 True 時，runserver 將會自動完成（請參閱 django.contrib.staticfiles.views.serve()）。

此方法效率極低，而且可能不安全，因此不適用於生產環境。

請參閱 如何部署靜態檔案，以了解在生產環境中提供靜態檔案的正確策略。

您的專案可能還會有不屬於特定應用程式的靜態資源。除了在您的應用程式中使用 static/ 目錄之外，您還可以在設定檔中定義一個目錄列表（STATICFILES_DIRS），Django 也會在其中尋找靜態檔案。例如

STATICFILES_DIRS = [
    BASE_DIR / "static",
    "/var/www/static/",
]

有關 staticfiles 如何尋找您的檔案的詳細資訊，請參閱 STATICFILES_FINDERS 設定的文件。

靜態檔案的命名空間

現在我們或許可以將靜態檔案直接放在 my_app/static/ 中（而不是建立另一個 my_app 子目錄），但這實際上會是一個壞主意。Django 會使用它找到的第一個名稱符合的靜態檔案，如果您在不同的應用程式中有一個名稱相同的靜態檔案，Django 將無法區分它們。我們需要能夠讓 Django 指向正確的檔案，而確保這一點的最佳方法是命名空間它們。也就是說，將這些靜態檔案放在以應用程式本身命名的另一個目錄中。

您可以透過指定 前綴，在 STATICFILES_DIRS 中為靜態資源設定命名空間。

在開發期間提供靜態檔案

如果您如上所述使用 django.contrib.staticfiles，當 DEBUG 設定為 True 時，runserver 將會自動執行此操作。如果您的 INSTALLED_APPS 中沒有 django.contrib.staticfiles，您仍然可以使用 django.views.static.serve() 視圖來手動提供靜態檔案。

這不適合在生產環境中使用！如需一些常見的部署策略，請參閱 如何部署靜態檔案。

例如，如果您的 STATIC_URL 定義為 static/，您可以透過將以下程式碼片段新增至您的 urls.py 來完成此操作

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

注意

此輔助函式僅在偵錯模式下且僅在給定的前綴是本機（例如 static/）而不是 URL（例如 http://static.example.com/）時才有效。

此外，此輔助函式僅提供實際的 STATIC_ROOT 資料夾；它不會執行像 django.contrib.staticfiles 一樣的靜態檔案探索。

最後，靜態檔案是透過 WSGI 應用程式層的封裝器提供的。因此，靜態檔案請求不會經過正常的 中介軟體鏈。

在開發期間提供使用者上傳的檔案

在開發期間，您可以使用 django.views.static.serve() 視圖，從 MEDIA_ROOT 提供使用者上傳的媒體檔案。

這不適合在生產環境中使用！如需一些常見的部署策略，請參閱 如何部署靜態檔案。

例如，如果您的 MEDIA_URL 定義為 media/，您可以透過將以下程式碼片段新增至您的 ROOT_URLCONF 來完成此操作

from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... the rest of your URLconf goes here ...
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)

注意

此輔助函式僅在偵錯模式下且僅在給定的前綴是本機（例如 media/）而不是 URL（例如 http://media.example.com/）時才有效。

測試

當執行使用實際 HTTP 請求而非內建測試用戶端的測試時（即，當使用內建的 LiveServerTestCase 時），需要沿著其餘內容提供靜態資源，以便測試環境盡可能忠實地重現真實環境，但是 LiveServerTestCase 僅具有非常基本的靜態檔案提供功能：它不知道 staticfiles 應用程式的尋找器功能，並假設靜態內容已收集在 STATIC_ROOT 下。

因此，staticfiles 提供了自己的 django.contrib.staticfiles.testing.StaticLiveServerTestCase，它是內建類別的子類別，能夠在這些測試執行期間透明地提供所有資源，方式與我們在開發時使用 DEBUG = True 獲得的方式非常相似，也就是說，無需先使用 collectstatic 來收集它們。

部署

django.contrib.staticfiles 提供了一個方便的管理命令，用於在單一目錄中收集靜態檔案，以便您可以輕鬆地提供它們。

  1. 將 STATIC_ROOT 設定設定為您想要從中提供這些檔案的目錄，例如

    STATIC_ROOT = "/var/www/example.com/static/"

  2. 執行 collectstatic 管理命令

    $ python manage.py collectstatic

    這會將您靜態資料夾中的所有檔案複製到 STATIC_ROOT 目錄。

  3. 使用您選擇的網路伺服器來提供檔案。如何部署靜態檔案 涵蓋了一些常見的靜態檔案部署策略。

了解更多

本文檔涵蓋了基本知識和一些常見的用法模式。 有關 django.contrib.staticfiles 中包含的所有設定、命令、範本標籤和其他部分的完整詳細資訊，請參閱 staticfiles 參考。

如何建立自訂範本標籤和篩選器
如何設定和使用日誌記錄
返回頂部