萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Django staticfiles 靜態檔案管理完整指南:配置、收集、部署

staticfiles 核心價值

Django 1.3+ 內建 django.contrib.staticfiles 解決分散在各 App 的靜態檔案 (CSS/JS/圖片) 統一收集、服務、版本控制問題。

三大核心設定

設定用途關鍵點
STATIC_ROOTcollectstatic 收集目標目錄絕對路徑,勿放入原始碼,僅部署時使用
STATIC_URL靜態檔案公開 URL 前綴模板中用 {% static 'path' %} 引用,必須以 / 結尾
STATICFILES_DIRS專案級/共用靜態檔案來源目錄列表/元組,不包含 App 內 static/ 目錄

settings.py 完整配置範例


import os
from pathlib import Path

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

# 開發環境
STATIC_URL = '/static/'
STATICFILES_DIRS = [
    BASE_DIR / 'static',           # 專案共用靜態檔案
    # BASE_DIR / 'frontend/dist',  # 前端建構產出
]

# 生產環境 (同檔或 production.py 覆蓋)
STATIC_ROOT = BASE_DIR / 'staticfiles'  # python manage.py collectstatic 目標

# 儲存後端 (生產建議)
# STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
# 或 WhiteNoise
# STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

App 內靜態檔案結構 (自動發現)


myapp/
├── static/
│   └── myapp/              # 必須以 app 名為子目錄 (命名空間隔離)
│       ├── css/
│       │   └── style.css
│       ├── js/
│       │   └── script.js
│       └── images/
│           └── logo.png
├── templates/
└── ...

模板引用:{% load static %}

開發模式自動服務

runserver 自動處理靜態檔案請求,**無需額外配置**。

原理:django.contrib.staticfiles.urls.staticfiles_urlpatterns() 自動加入 URLconf。

生產部署:collectstatic 流程


# 1. 收集所有靜態檔案到 STATIC_ROOT
python manage.py collectstatic --noinput --clear

# 2. 配置 Web 伺服器直接服務 STATIC_ROOT
# Nginx 範例
location /static/ {
    alias /path/to/project/staticfiles/;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

進階儲存後端

1. ManifestStaticFilesStorage (內建)

  • 檔案名加入內容雜湊:style.css → style.a1b2c3d4.css
  • 生成 staticfiles.json 對應表
  • 解決瀏覽器快取失效問題

2. WhiteNoise (推薦:簡單高效)


# settings.py
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',  # 放在 SecurityMiddleware 之後
    # ...
]

STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'

# 效果:Gzip/Brotli 壓縮 + 雜湊檔名 + 高效服務,無需 Nginx 靜態檔案配置

3. 雲端儲存 (S3/GCS/Azure)


# django-storages
INSTALLED_APPS += ['storages']

AWS_STORAGE_BUCKET_NAME = 'my-bucket'
AWS_S3_REGION_NAME = 'ap-northeast-1'
STATICFILES_STORAGE = 'storages.backends.s3boto3.S3Boto3Storage'

常見問題排查

現象原因解決
開發環境 404未執行 collectstatic (開發不需要) / DEBUG=False設 DEBUG=True,確認 staticfiles 在 INSTALLED_APPS
生產 404Nginx 未指向 STATIC_ROOT / 未執行 collectstatic檢查 Nginx alias 路徑,執行 collectstatic
檔案未更新瀏覽器/CDN 快取用 ManifestStorage 或手動版本號 ?v=2
Admin 介面無樣式django.contrib.admin 靜態檔案未收集執行 collectstatic,確認 django.contrib.staticfiles 載入順序在 admin 之前
找不到檔案STATICFILES_DIRS 路徑錯誤 / App 目錄結構錯誤確認 static/app_name/ 結構,用 findstatic 除錯

除錯神器


# 尋找靜態檔案實際路徑
python manage.py findstatic css/base.css --verbosity=2

# 列出所有會被收集的檔案
python manage.py collectstatic --dry-run --verbosity=2

最佳實踐清單

  1. ✅ STATIC_ROOT 指向部署專用目錄,**不提交版控**
  2. ✅ 專案共用靜態檔放 STATICFILES_DIRS,App 專用放 app/static/app/
  3. ✅ 模板**必須**用 {% static %} 標籤,不可硬編碼 URL
  4. ✅ 生產啟用 ManifestStaticFilesStorage 或 WhiteNoise
  5. ✅ Nginx/Apache 直接服務靜態檔案,不經 Django
  6. ✅ 前端建構產出 (Webpack/Vite) 輸出到 STATICFILES_DIRS 目錄
copyright © 萬盛學電腦網 all rights reserved