使用 WhiteNoise 簡化 Django 靜態文件管理：新手入門指南

更新日期： 2025 年 1 月 1 日

在 Django 中管理靜態文件是開發與部署的重要部分。

當切換到生產環境（DEBUG=False）時，Django 停止提供靜態文件，這通常會導致網站的樣式和腳本無法正常加載。

WhiteNoise 是一個輕量級解決方案，它讓 Django 能直接提供靜態文件，而無需依賴 Nginx 或 Apache。

本指南將教您如何使用 WhiteNoise 簡化靜態文件的管理。

什麼是 WhiteNoise？

WhiteNoise 的功能

WhiteNoise 是一個專為 Django 設計的中間件，主要用於：

• 在生產環境中提供靜態文件服務。
• 不依賴外部伺服器（如 Nginx 或 Apache）。
• 支援文件壓縮和緩存優化。

WhiteNoise 解決的問題

• 靜態文件的提供：當 DEBUG=False 時，Django 停止自動提供靜態文件。如果未正確配置外部伺服器，可能會出現靜態文件 404 錯誤。
• 性能優化：WhiteNoise 支持壓縮靜態文件和設置緩存標頭，減少文件加載時間並優化用戶體驗。

如何配置 WhiteNoise？

以下是從安裝到使用 WhiteNoise 的完整步驟。

安裝 WhiteNoise

使用 Poetry 或 pip 安裝 WhiteNoise：

poetry add whitenoise
# 或
pip install whitenoise

添加 WhiteNoise 中間件

在 settings.py 的 MIDDLEWARE 列表中，添加 WhiteNoise 中間件，並確保其位置在 SecurityMiddleware 之後：

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    # 其他中間件
]

配置靜態文件設置

在 settings.py 中，設置靜態文件相關配置：

STATIC_URL = "/static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",  # 應用開發中使用的靜態文件目錄
]
STATIC_ROOT = BASE_DIR / "staticfiles"  # 生產環境中集中存放靜態文件

收集靜態文件

執行以下命令將所有應用的靜態文件集中到 STATIC_ROOT 中：

python manage.py collectstatic

此命令會將所有 static/ 目錄中的文件複製到 staticfiles/ 目錄，便於生產環境使用。

測試靜態文件

啟動 Django 開發伺服器，並確保靜態文件可以正確加載。

例如，訪問：

http://127.0.0.1:8000/static/styles/app.css

靜態文件應該正常加載。

進一步優化：壓縮與緩存

WhiteNoise 支持文件壓縮和緩存設置，進一步提高靜態文件的性能。

啟用壓縮與緩存優化

在 settings.py 中設置：

STATICFILES_STORAGE = "whitenoise.storage.CompressedManifestStaticFilesStorage"

壓縮功能

WhiteNoise 會自動生成 .gz 和 .br 格式的壓縮文件，瀏覽器會優先加載這些壓縮版本，減少靜態文件的傳輸大小。

緩存優化

WhiteNoise 通過為每個靜態文件生成唯一的哈希名稱（例如 app.a1b2c3.css），確保文件更新後瀏覽器能立即獲取新版本，而不是從緩存中加載舊文件。

生產環境測試

切換到生產模式

在 settings.py 中將 DEBUG 設為 False：

DEBUG = False
ALLOWED_HOSTS = ["yourdomain.com", "127.0.0.1"]

測試靜態文件

重啟伺服器，檢查瀏覽器中的靜態文件是否正確加載。可以在開發工具中查看文件是否來自 /static/ 路徑，並檢查是否已啟用壓縮（如 .gz 文件）。

WhiteNoise 的優勢與適用場景

優勢

1. 無需外部伺服器：WhiteNoise 適合不想配置 Nginx 或 Apache 的小型專案。
2. 簡單集成：安裝與配置非常簡單，適合初學者。
3. 性能優化：支持壓縮和緩存功能，提升用戶體驗。

適用場景

• 小型專案：無需部署複雜的靜態文件伺服器。
• 測試環境：快速驗證生產環境配置。
• 臨時部署：為應急場景提供靜態文件支持。

結語

雖然 WhiteNoise 是一個高效的解決方案，但在大型專案或高流量網站中，建議結合 Nginx 或其他專業的靜態文件伺服器來處理靜態文件，以獲得更高效能與安全性。

WhiteNoise 為 Django 提供了一個便捷的靜態文件管理解決方案，尤其適合初學者或小型專案。

在經過正確配置後，您可以輕鬆管理靜態文件，並確保它們在生產環境中正常運作。