Django 1.3+ 內建 django.contrib.staticfiles 解決分散在各 App 的靜態檔案 (CSS/JS/圖片) 統一收集、服務、版本控制問題。
| 設定 | 用途 | 關鍵點 |
|---|---|---|
STATIC_ROOT | collectstatic 收集目標目錄 | 絕對路徑,勿放入原始碼,僅部署時使用 |
STATIC_URL | 靜態檔案公開 URL 前綴 | 模板中用 {% static 'path' %} 引用,必須以 / 結尾 |
STATICFILES_DIRS | 專案級/共用靜態檔案來源目錄 | 列表/元組,不包含 App 內 static/ 目錄 |
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'
myapp/
├── static/
│ └── myapp/ # 必須以 app 名為子目錄 (命名空間隔離)
│ ├── css/
│ │ └── style.css
│ ├── js/
│ │ └── script.js
│ └── images/
│ └── logo.png
├── templates/
└── ...
模板引用:{% load static %}
runserver 自動處理靜態檔案請求,**無需額外配置**。
原理:django.contrib.staticfiles.urls.staticfiles_urlpatterns() 自動加入 URLconf。
# 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";
}
style.css → style.a1b2c3d4.cssstaticfiles.json 對應表
# settings.py
MIDDLEWARE = [
'django.middleware.security.SecurityMiddleware',
'whitenoise.middleware.WhiteNoiseMiddleware', # 放在 SecurityMiddleware 之後
# ...
]
STATICFILES_STORAGE = 'whitenoise.storage.CompressedManifestStaticFilesStorage'
# 效果:Gzip/Brotli 壓縮 + 雜湊檔名 + 高效服務,無需 Nginx 靜態檔案配置
# 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 |
| 生產 404 | Nginx 未指向 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
STATIC_ROOT 指向部署專用目錄,**不提交版控**STATICFILES_DIRS,App 專用放 app/static/app/{% static %} 標籤,不可硬編碼 URLManifestStaticFilesStorage 或 WhiteNoiseSTATICFILES_DIRS 目錄