Django 靜態文件管理：static 與 staticfiles 完整指南

更新日期： 2025 年 1 月 1 日

Django 是一個功能強大的 Web 框架，支持靜態文件的高效管理。

然而，靜態文件的開發與生產環境需求不同，需要採取不同的處理方式。

本指南將幫助新手了解 static 和 staticfiles 的核心概念、區別以及實際應用，確保靜態文件在開發與部署環境中能正常運作。

static 與 staticfiles 的區別

什麼是 static？

• 靜態文件的源目錄：每個應用的 static/ 目錄是專為該應用設計的，用於存放 CSS、JS、圖片等資源。
• 適用於開發環境：當 DEBUG=True 時，Django 的內建伺服器會自動從這些目錄提供文件。

範例

假設有以下目錄結構：

app1/
    static/
        css/
            style.css
app2/
    static/
        js/
            script.js

在模板中，可以通過 {% static %} 標籤加載靜態文件：

<link rel="stylesheet" href="{% static 'css/style.css' %}">

當 DEBUG=True 時，Django 會從 app1/static/css/style.css 提供該文件。

什麼是 staticfiles？

• 靜態文件的統一存放目錄：生產環境中，所有應用的靜態文件會集中到 STATIC_ROOT 指定的目錄中，通常被稱為 staticfiles。
• 生產環境專用：當執行 collectstatic 命令時，Django 將所有應用的 static/ 文件以及 STATICFILES_DIRS 中指定的文件複製到 STATIC_ROOT。
• 需外部伺服器提供服務：例如 Nginx 或 Apache。

範例

假設 STATIC_ROOT 設置為 staticfiles/，執行 collectstatic 後：

staticfiles/
    css/
        style.css
    js/
        script.js

生產環境中，外部伺服器會直接從 staticfiles/ 提供靜態文件，而不再依賴分散的應用目錄。

配置靜態文件

settings.py 配置

開發環境

STATIC_URL = '/static/'

• STATIC_URL：定義靜態文件的 URL 路徑前綴，用於模板中靜態文件的引用。

生產環境

STATIC_URL = '/static/'
STATIC_ROOT = BASE_DIR / "staticfiles"

• STATIC_ROOT：指定 collectstatic 收集靜態文件的目錄。

收集靜態文件

執行以下命令：

python manage.py collectstatic

Django 會掃描所有應用的 static/ 目錄，以及 STATICFILES_DIRS 中的路徑，將文件複製到 STATIC_ROOT。

如何使用 staticfiles 在生產環境提供服務？

外部伺服器配置

通常使用 Nginx 或 Apache 等伺服器來處理 STATIC_ROOT 目錄中的靜態文件。

Nginx 配置範例

location /static/ {
    alias /path/to/staticfiles/;
}

臨時使用 Django 提供靜態文件

如果沒有配置外部伺服器，可以暫時使用 Django 處理靜態文件。

更新 urls.py：

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

if not settings.DEBUG:
    urlpatterns += static(settings.STATIC_URL, document_root=settings.STATIC_ROOT)

static 與 staticfiles 的對比

部署靜態文件的完整流程

1. 開發環境

1. 配置 STATIC_URL。
2. 在應用的 static/ 目錄中存放靜態文件。
3. 使用 {% static %} 標籤引用文件。

生產環境

1. 配置 STATIC_URL 和 STATIC_ROOT。
2. 執行 python manage.py collectstatic。
3. 使用外部伺服器（如 Nginx）處理 STATIC_ROOT 中的靜態文件。

注意事項與最佳實踐

1. 開發與生產環境的區別
   • 開發環境中，Django 直接服務 static/ 文件。
   • 生產環境中，所有靜態文件應該集中到 STATIC_ROOT，並由外部伺服器提供。
2. 安全性建議
   • 不建議在生產環境中讓 Django 提供靜態文件服務，應使用專門的靜態文件伺服器。
3. 測試環境建議
   • 測試環境可暫時使用 Django 處理靜態文件，確保功能正確。

結語

靜態文件的管理是 Django 開發與部署的重要一環。

通過正確區分和配置 static 與 staticfiles，您可以在開發環境中快速迭代設計，並在生產環境中高效提供靜態資源。

希望本指南能幫助您更清晰地理解並正確應用這些功能！ 🎉