Django-storages 與 STORAGES 配置：未來相容性的最佳實踐

By徐培鈞
LinkedIn

更新日期： 2024 年 12 月 18 日

本文為 圖片上傳 AWS S3 系列教學，第 18 篇：

  1. AWS S3 是什麼？
  2. boto3 與 django-storages：如何在 Django 中對接 AWS S3
  3. AWS S3 與 IAM：圖片上傳功能的權限管理指南
  4. S3 與 Postgres 的比較與應用
  5. Amazon S3 物件所有權設定解析
  6. AWS S3「阻止所有公開訪問」設定說明
  7. Amazon S3 儲存桶版本控制完整指南
  8. 如何設定 S3 儲存桶的「預設加密」？—— 初學者指南
  9. S3 儲存桶標籤（Tags）簡單介紹：讓你的 S3 管理更輕鬆！
  10. AWS S3 物件鎖定功能入門指南
  11. AWS S3 公開存取權完整指南
  12. AWS CORS 預檢請求與設定指南
  13. AWS IAM 設定教學：生成訪問密鑰以用於 S3 配置
  14. django-storages 基本配置：讓應用程式連接 S3 存儲桶
  15. Django-storages 的完整配置教學：從隱密性到快取控制
  16. Django-storages 完整配置指南：從文件存儲到訪問路徑
  17. Django-storages 配置：環境變數設定
  18. Django-storages 與 STORAGES 配置：未來相容性的最佳實踐　👈 所在位置
  19. 如何在 Django 中移除 DEBUG URL 的靜態檔案配置

建議閱讀本文前，先閱讀完 圖片上傳功能 系列文

隨著 Django 的持續更新，DEFAULT_FILE_STORAGE 設定雖然在 Django 5.1.4 中仍然可用，但已被標記為過時。

新版本推薦使用更靈活且結構化的 STORAGES 設定方式來替代。

這篇文章將帶你了解如何遷移到 STORAGES，並解決與靜態文件相關的問題。

為什麼需要從 DEFAULT_FILE_STORAGE 遷移到 STORAGES？

短期影響

目前，DEFAULT_FILE_STORAGE 在 Django 5.1.4 中仍然可以正常使用，但可能會觸發開發工具或 IDE 的過時警告訊息。

這意味著該方法在未來的版本中可能完全被移除。

長期影響

隨著 Django 的演進，繼續使用 DEFAULT_FILE_STORAGE 可能導致：

  • 非相容性問題：升級 Django 版本時應用程式可能無法運行。
  • 技術負債：需要額外的時間和精力進行緊急修正。

為了確保專案的穩定性與可維護性，建議儘早遷移到 STORAGES 設定方式。

如何遷移到 STORAGES？

傳統設定：DEFAULT_FILE_STORAGE

在舊版本中，你可能使用以下方式設置媒體文件的存儲：

DEFAULT_FILE_STORAGE = "storages.backends.s3boto3.S3Boto3Storage"

新式設定：STORAGES

使用 STORAGES 可以更靈活地配置媒體文件與靜態文件的存儲方式：

STORAGES = {
    "default": {  # 用於媒體文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
        },
    },
}

如何配置靜態文件？

在使用 STORAGES 設定時，必須同時指定 staticfiles 的存儲後端，否則可能出現錯誤提示。

選項 1：將靜態文件存儲到 S3

如果希望靜態文件也存儲到 S3，可以在 STORAGES 中新增以下內容：

STORAGES = {
    "default": {  # 媒體文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
            "default_acl": AWS_DEFAULT_ACL,
            "querystring_auth": AWS_QUERYSTRING_AUTH,
            "object_parameters": AWS_S3_OBJECT_PARAMETERS,
            "custom_domain": AWS_S3_CUSTOM_DOMAIN,
        },
    },
    "staticfiles": {  # 靜態文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
            "default_acl": AWS_DEFAULT_ACL,
            "querystring_auth": AWS_QUERYSTRING_AUTH,
            "object_parameters": AWS_S3_OBJECT_PARAMETERS,
            "custom_domain": AWS_S3_CUSTOM_DOMAIN,
        },
    },
}
STATIC_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/static/"

選項 2：保留本地存儲

如果希望靜態文件繼續保存在本地，可以設置 staticfiles 為本地存儲：

STORAGES = {
    "default": {  # 媒體文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
            "default_acl": AWS_DEFAULT_ACL,
            "querystring_auth": AWS_QUERYSTRING_AUTH,
            "object_parameters": AWS_S3_OBJECT_PARAMETERS,
            "custom_domain": AWS_S3_CUSTOM_DOMAIN,
        },
    },
    "staticfiles": {  # 本地靜態文件
        "BACKEND": "django.contrib.staticfiles.storage.StaticFilesStorage",
    },
}
STATIC_URL = "/static/"

設定重點解讀

遷移的改動點

  1. 移除 DEFAULT_FILE_STORAGE
    過去的單一配置方式被替代，取而代之的是更具結構化的 STORAGES 設定。
  2. 新增靜態文件的存儲配置
    在 STORAGES 中必須明確指定 staticfiles 的後端存儲方式，否則可能導致開發環境或生產環境的錯誤。

遷移的好處

  • 相容未來版本：STORAGES 是 Django 的官方推薦方式，能保證未來版本的相容性。
  • 結構清晰：靜態文件與媒體文件的存儲方式分開管理，易於維護和修改。

完整配置範例

以下是基於 S3 的完整 STORAGES 配置範例，涵蓋媒體文件和靜態文件的存儲設定：

from dotenv import load_dotenv
import os

# 加載環境變數
load_dotenv()

AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_STORAGE_BUCKET_NAME = os.getenv("AWS_STORAGE_BUCKET_NAME")
AWS_S3_REGION_NAME = os.getenv("AWS_S3_REGION_NAME")
AWS_S3_CUSTOM_DOMAIN = f"{AWS_STORAGE_BUCKET_NAME}.s3.{AWS_S3_REGION_NAME}.amazonaws.com"

AWS_DEFAULT_ACL = None
AWS_QUERYSTRING_AUTH = False
AWS_S3_OBJECT_PARAMETERS = {"CacheControl": "max-age=86400"}

MEDIA_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/media/"
STATIC_URL = f"https://{AWS_S3_CUSTOM_DOMAIN}/static/"

STORAGES = {
    "default": {  # 媒體文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
            "default_acl": AWS_DEFAULT_ACL,
            "querystring_auth": AWS_QUERYSTRING_AUTH,
            "object_parameters": AWS_S3_OBJECT_PARAMETERS,
            "custom_domain": AWS_S3_CUSTOM_DOMAIN,
        },
    },
    "staticfiles": {  # 靜態文件
        "BACKEND": "storages.backends.s3boto3.S3Boto3Storage",
        "OPTIONS": {
            "access_key": AWS_ACCESS_KEY_ID,
            "secret_key": AWS_SECRET_ACCESS_KEY,
            "bucket_name": AWS_STORAGE_BUCKET_NAME,
            "region_name": AWS_S3_REGION_NAME,
            "default_acl": AWS_DEFAULT_ACL,
            "querystring_auth": AWS_QUERYSTRING_AUTH,
            "object_parameters": AWS_S3_OBJECT_PARAMETERS,
            "custom_domain": AWS_S3_CUSTOM_DOMAIN,
        },
    },
}

結論與最佳實踐

  1. 立即遷移到 STORAGES
    遷移不僅能確保相容性，還能讓你的配置更加靈活與清晰。
  2. 針對靜態文件選擇合適的存儲方式
    根據專案需求，靜態文件可以選擇存放在 S3 或保留在本地。
  3. 環境變數管理敏感資訊
    使用 .env 文件和 python-dotenv 工具來管理憑證，避免將敏感資訊硬編碼到程式中。

遷移到 STORAGES 不僅是為了相容性，更是遵循 Django 的最佳實踐，讓你的專案在未來能穩定運行。

Similar Posts

新手指南：在 Django 中實作標籤功能的表單與保存邏輯

By徐培鈞

在 Django 中，為模型設置標籤是一個常見的需求，例如為文章添加主題標籤、為服務分類標籤等。

當涉及表單提交與多對多關係保存時，可能會讓新手感到困惑，特別是處理標籤數據的邏輯。

本文將通過詳細解說範例代碼，幫助新手理解如何設計表單、編寫後端處理函數，以及為什麼需要特定的保存步驟。

使用 Django 樣板繼承實現頁面佈局共享

By徐培鈞

當我們使用 Django 的模板系統渲染頁面時，會遇到一個問題：

每個 HTML 文件都需要手動添加相同的標籤，例如 header、body 等，這不僅繁瑣，還容易導致代碼重複和維護困難。

為了解決這個問題，我們可以利用 Django 的樣板繼承功能，實現頁面佈局的共享。