Django 設定檔深入解析：settings.py 完全指南 | Django 教學

# manage.py 中的預設設定
import os
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'myproject.settings')

# 開發環境：開啟 DEBUG 模式
DEBUG = True

# 生產環境：必須關閉 DEBUG 模式
DEBUG = False

# Django 自動產生的 SECRET_KEY（僅供開發使用）
SECRET_KEY = 'django-insecure-abc123...'

# 正式環境：從環境變數讀取
import os
SECRET_KEY = os.environ.get('DJANGO_SECRET_KEY')

# 使用 Django 內建工具產生安全的 SECRET_KEY
from django.core.management.utils import get_random_secret_key
print(get_random_secret_key())
# 輸出範例：'v$2x!k8g#m^r7&9_qwp...'

# 開發環境
ALLOWED_HOSTS = ['localhost', '127.0.0.1']

# 生產環境：設定實際域名
ALLOWED_HOSTS = ['example.com', 'www.example.com']

# 允許所有子域名（使用前綴 . 號）
ALLOWED_HOSTS = ['.example.com']

# 危險！不建議在生產環境使用萬用字元
ALLOWED_HOSTS = ['*']

INSTALLED_APPS = [
    # === Django 內建 App ===
    'django.contrib.admin',          # 管理後台
    'django.contrib.auth',           # 認證系統
    'django.contrib.contenttypes',   # Content Type 框架
    'django.contrib.sessions',       # Session 框架
    'django.contrib.messages',       # 訊息框架
    'django.contrib.staticfiles',    # 靜態檔案管理

    # === 第三方套件 ===
    'rest_framework',                # Django REST Framework
    'corsheaders',                   # CORS 跨域設定
    'django_extensions',             # 開發工具擴充

    # === 自訂 App ===
    'apps.users.apps.UsersConfig',   # 使用者管理
    'apps.articles',                 # 文章管理
]

# 預設的 SQLite 設定
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': BASE_DIR / 'db.sqlite3',
    }
}

# 安裝 PostgreSQL 驅動
pip install psycopg2-binary

# PostgreSQL 設定範例
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'myproject_db',        # 資料庫名稱
        'USER': 'myproject_user',      # 資料庫使用者
        'PASSWORD': 'secure_password', # 資料庫密碼
        'HOST': 'localhost',           # 資料庫主機
        'PORT': '5432',               # 預設 PostgreSQL 端口
        'OPTIONS': {
            'connect_timeout': 10,     # 連線逾時（秒）
        },
    }
}

# 靜態檔案的 URL 前綴
# 瀏覽器存取靜態檔案時使用此路徑，例如 /static/css/style.css
STATIC_URL = '/static/'

# 額外的靜態檔案目錄（開發時期使用）
# Django 開發伺服器會從這些目錄中查找靜態檔案
STATICFILES_DIRS = [
    BASE_DIR / 'static',          # 專案根目錄下的 static 資料夾
    BASE_DIR / 'assets',          # 也可以指定其他目錄
]

# collectstatic 指令的目標目錄（部署時期使用）
# 執行 python manage.py collectstatic 後，所有靜態檔案會被收集到此目錄
STATIC_ROOT = BASE_DIR / 'staticfiles'

# 使用者上傳檔案的 URL 前綴
MEDIA_URL = '/media/'

# 使用者上傳檔案的實際儲存路徑
MEDIA_ROOT = BASE_DIR / 'media'

# myproject/urls.py
from django.conf import settings
from django.conf.urls.static import static

urlpatterns = [
    # ... 其他 URL 設定
]

# 僅在 DEBUG 模式下提供 media 檔案服務
if settings.DEBUG:
    urlpatterns += static(
        settings.MEDIA_URL,
        document_root=settings.MEDIA_ROOT
    )

TEMPLATES = [
    {
        # 使用 Django 內建的模板引擎
        'BACKEND': 'django.template.backends.django.DjangoTemplates',

        # 全域模板目錄（優先查找）
        'DIRS': [BASE_DIR / 'templates'],

        # 是否自動搜尋每個 App 的 templates/ 子目錄
        'APP_DIRS': True,

        'OPTIONS': {
            # 上下文處理器：自動注入到每個 Template 的變數
            'context_processors': [
                'django.template.context_processors.debug',    # debug 變數
                'django.template.context_processors.request',  # request 物件
                'django.contrib.auth.context_processors.auth', # user、perms 變數
                'django.contrib.messages.context_processors.messages',  # messages 變數
            ],
        },
    },
]

MIDDLEWARE = [
    # 安全性中介軟體（必須放在最前面）
    'django.middleware.security.SecurityMiddleware',

    # Session 中介軟體（認證之前必須先有 Session）
    'django.contrib.sessions.middleware.SessionMiddleware',

    # 通用中介軟體（處理 URL 尾端斜線、Content-Length 等）
    'django.middleware.common.CommonMiddleware',

    # CSRF 防護（表單提交前必須驗證）
    'django.middleware.csrf.CsrfViewMiddleware',

    # 認證中介軟體（依賴 Session，因此必須在 SessionMiddleware 之後）
    'django.contrib.auth.middleware.AuthenticationMiddleware',

    # 訊息框架中介軟體
    'django.contrib.messages.middleware.MessageMiddleware',

    # 防止頁面被嵌入 iframe（點擊劫持防護）
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]

# 預設語言代碼
# 使用 IETF 語言標籤格式，如 'en-us'、'zh-hant'
LANGUAGE_CODE = 'zh-hant'

# 預設時區
# 完整清單：https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
TIME_ZONE = 'Asia/Taipei'

# 是否啟用 Django 的翻譯系統
# True：Django 會根據使用者的語言偏好提供對應的翻譯
USE_I18N = True

# 是否啟用時區感知（Timezone-aware）的日期時間處理
# True：資料庫儲存 UTC 時間，顯示時自動轉換為 TIME_ZONE 指定的時區
USE_TZ = True

# 當 USE_TZ = True 時
from django.utils import timezone

# 正確做法：使用 timezone-aware 的時間
now = timezone.now()  # 回傳 UTC 時間，帶有時區資訊

# 錯誤做法：使用 naive datetime（不帶時區資訊）
import datetime
now = datetime.datetime.now()  # 這在 USE_TZ = True 時可能引發警告

# 安裝 python-decouple
pip install python-decouple

# .env（此檔案不可提交至 Git）
DJANGO_SECRET_KEY=v$2x!k8g#m^r7&9_qwp...your-actual-secret-key
DJANGO_DEBUG=True
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
DB_ENGINE=django.db.backends.postgresql
DB_NAME=myproject_db
DB_USER=myproject_user
DB_PASSWORD=secure_password
DB_HOST=localhost
DB_PORT=5432

# .gitignore
.env

# settings.py
from decouple import config, Csv
from pathlib import Path

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

# 安全金鑰：從環境變數讀取，沒有預設值（未設定時會報錯）
SECRET_KEY = config('DJANGO_SECRET_KEY')

# DEBUG 模式：自動將字串轉為布林值，預設為 False
DEBUG = config('DJANGO_DEBUG', default=False, cast=bool)

# ALLOWED_HOSTS：使用 Csv() 將逗號分隔的字串轉為 List
ALLOWED_HOSTS = config('DJANGO_ALLOWED_HOSTS', default='', cast=Csv())

# 資料庫設定
DATABASES = {
    'default': {
        'ENGINE': config('DB_ENGINE', default='django.db.backends.sqlite3'),
        'NAME': config('DB_NAME', default=str(BASE_DIR / 'db.sqlite3')),
        'USER': config('DB_USER', default=''),
        'PASSWORD': config('DB_PASSWORD', default=''),
        'HOST': config('DB_HOST', default=''),
        'PORT': config('DB_PORT', default=''),
    }
}

from decouple import config, Csv

# 基本讀取（字串）
secret = config('DJANGO_SECRET_KEY')

# 型別轉換：cast 參數
debug = config('DJANGO_DEBUG', cast=bool)           # 字串 → 布林值
port = config('DB_PORT', cast=int)                   # 字串 → 整數
hosts = config('ALLOWED_HOSTS', cast=Csv())          # 逗號分隔字串 → List

# 預設值：當環境變數不存在時使用
timeout = config('REQUEST_TIMEOUT', default=30, cast=int)