使用 Python-dotenv 管理環境變數：完整指南

更新日期： 2025 年 2 月 12 日

在開發 Python 應用程式時，經常需要使用 API 金鑰、資料庫連線字串等敏感資訊。

如果直接將這些資訊寫入程式碼，可能會造成安全風險，甚至不小心將憑證暴露到版本控制系統（如 Git）。

為了有效管理這些環境變數，python-dotenv 提供了一種簡單且安全的方式，讓開發者可以將環境變數存儲在 .env 檔案中，並在程式運行時自動載入它們。

本文將詳細介紹 python-dotenv 的安裝、使用方法及最佳實踐，幫助你在專案中更好地管理環境變數。

什麼是 Python-dotenv？

python-dotenv 是一個用來讀取 .env 檔案的 Python 套件。

.env 檔案通常包含環境變數，例如 API 金鑰、資料庫連線資訊等，該套件可以幫助我們將這些變數自動載入到 Python 的環境中，避免將敏感資訊硬編碼在程式碼裡。

為什麼需要使用 python-dotenv？

1. 提高安全性：將 API 金鑰等機密資訊存放於 .env 檔案，而不是直接寫入程式碼，避免洩漏風險。
2. 版本控制安全：可以將 .env 檔案加入 .gitignore，防止其被提交到 Git 儲存庫。
3. 更好的可維護性：環境變數集中管理，使專案設定更加清晰、可讀性更高。
4. 跨環境適應：允許開發、測試和正式環境使用不同的設定，無需修改程式碼。

如果不使用 python-dotenv 套件

如果不使用 python-dotenv 套件，需手動讀取 .env 檔案並載入環境變數。

以下是一種方法：

import os

def load_env_file(env_path=".env"):
    """手動讀取 .env 檔案並載入到環境變數"""
    if not os.path.exists(env_path):
        raise FileNotFoundError(f"{env_path} 檔案不存在")

    with open(env_path, "r", encoding="utf-8") as file:
        for line in file:
            line = line.strip()
            if not line or line.startswith("#"):  # 忽略空行和註解
                continue
            key, _, value = line.partition("=")  # 解析 key=value 格式
            os.environ[key.strip()] = value.strip()

# 載入 .env 檔案
load_env_file()

# 取得環境變數
database_url = os.getenv("DATABASE_URL")
api_key = os.getenv("API_KEY")
debug_mode = os.getenv("DEBUG", "False")  # 預設值為 False

print(f"Database URL: {database_url}")
print(f"API Key: {api_key}")
print(f"Debug Mode: {debug_mode}")

方法解析

1. 手動開啟 .env 檔案，逐行讀取內容。
2. 忽略空行和註解（以 # 開頭的行）。
3. 解析 key=value 格式，並存入 os.environ，讓 Python 可使用 os.getenv() 來存取變數。

這種方法雖然不需要安裝額外的套件，但 python-dotenv 提供了更多功能，例如自動處理數據類型、讀取不同 .env 檔案等。

Python-dotenv 的安裝與基本使用

安裝 python-dotenv

要使用 python-dotenv，首先需要安裝該套件。可以使用 pip 進行安裝：

pip install python-dotenv

建立 .env 檔案

在專案的根目錄下建立一個名為 .env 的檔案，並在其中定義環境變數。例如：

DATABASE_URL=mysql://user:password@localhost/dbname
API_KEY=your_api_key_here
DEBUG=True

在 Python 程式中載入 .env 檔案

在 Python 腳本或應用程式中，使用 dotenv 來載入 .env 檔案：

from dotenv import load_dotenv
import os

# 載入 .env 檔案
load_dotenv()

# 取得環境變數
database_url = os.getenv("DATABASE_URL")
api_key = os.getenv("API_KEY")
debug_mode = os.getenv("DEBUG")

print(f"Database URL: {database_url}")
print(f"API Key: {api_key}")
print(f"Debug Mode: {debug_mode}")

這段程式碼會從 .env 檔案中讀取變數，並透過 os.getenv() 取得它們的值。

進階用法

指定 .env 檔案路徑

如果 .env 檔案不在專案的根目錄下，可以手動指定路徑：

from dotenv import load_dotenv
import os

load_dotenv(dotenv_path="/path/to/your/.env")  # 指定 .env 檔案路徑

檢查環境變數是否存在

為了確保環境變數已正確載入，可以使用 os.getenv() 檢查它是否為 None：

api_key = os.getenv("API_KEY")

if api_key is None:
    raise ValueError("API_KEY 未設定，請檢查 .env 檔案")

自動覆寫環境變數

如果 .env 檔案中的變數與系統環境變數重疊，預設情況下 load_dotenv() 不會 覆寫現有的環境變數。

如果希望強制覆寫，可以設定 override=True：

load_dotenv(override=True)

使用 dotenv CLI 讀取變數

除了在 Python 程式中使用 python-dotenv，也可以透過 CLI 直接讀取 .env 檔案的變數。例如：

dotenv list

如果要在執行指令時載入 .env 變數，可以使用：

dotenv run -- python my_script.py

這樣可以確保 my_script.py 在執行時讀取 .env 檔案中的變數。

最佳實踐

1. 不要將 .env 檔案提交到版本控制系統
   • 可以在 .gitignore 檔案中加入 .env 來避免洩漏敏感資訊。
2. 提供 .env.example 範本
   • 讓團隊成員知道應該設定哪些變數，格式如下：

DATABASE_URL=
API_KEY=
DEBUG=

3. 設定環境變數的預設值
   • 在程式中，如果環境變數未設定，可以提供預設值：

debug_mode = os.getenv("DEBUG", "False")  # 預設為 False

4. 區分不同環境的 .env 檔案
   • 可以根據不同的環境（開發、測試、正式環境）使用不同的 .env 檔案
   • 然後在程式中根據需求載入對應的 .env
   • 例如：

.env.development
.env.testing
.env.production

import os
from dotenv import load_dotenv

env_file = f".env.{os.getenv('APP_ENV', 'development')}"
load_dotenv(env_file)

結論

python-dotenv 是管理環境變數的最佳選擇之一，特別適合需要存儲 API 金鑰、資料庫憑證等敏感資訊的專案。

透過 .env 檔案，我們可以輕鬆管理不同環境的設定，避免將機密資訊直接寫入程式碼中，從而提高專案的安全性和可維護性。

如果你還沒有在專案中使用 python-dotenv，現在就試試看吧！