Python代码中怎么设置和读取环境变量

宋时安

发布时间：2026-10-22 | 5人浏览过

原创

在 Python 代码中，管理环境变量的核心工具是标准库提供的 os 模块。最基础的做法是通过 os.environ 字典对象直接设置与读取，或者借助快捷函数 os.getenv() 设置备用默认值。本文将深入阐述读取与设置的具体代码写法、底层生效范围、类型转换细节以及工程化落地实践。

一、核心原理：Python 进程如何与环境变量交互

环境变量是操作系统提供给进程运行时的上下文键值对。当操作系统启动一个 Python 进程时，会将当前系统及父进程（如终端 Shell）的环境变量复制一份快照传入 Python 运行环境。

在 Python 内部，os.environ 是一个映射对象（Mapping），代表当前进程所持有的环境变量视图。由于进程隔离机制的存在，我们在 Python 代码中对 os.environ 所作的所有增删改操作，仅对当前 Python 进程及其随后派生出的子进程生效，绝不会反向修改操作系统的全局配置或启动脚本的终端 Shell 环境。一旦 Python 进程退出，在代码中赋予的环境变量值就会随内存回收而彻底消失。

图1：Python 进程与操作系统环境变量的单向复制及子进程继承机制

二、Python 代码中读取环境变量的3种方法

Python 提供了两种主要入口来读取环境变量：os.environ 字典索引/方法，以及标准便捷函数 os.getenv()。根据是否允许配置缺失，我们可以选择不同的调用方式。

1. 安全读取并设定默认值：os.getenv()

os.getenv(key, default=None) 是最常用的读取途径。当指定的变量名不存在时，它不会引发异常，而是返回你指定的默认值（未指定则返回 None）。

import os

# 读取可选配置，如果未设置则采用默认端口 8080
server_port = os.getenv("PORT", "8080")
print(f"服务端口: {server_port}")

# 读取未设置的环境变量，默认返回 None
db_password = os.getenv("DB_PASSWORD")
if db_password is None:
    print("未检测到数据库密码配置")

2. 字典风格的安全读取：os.environ.get()

因为 os.environ 实现了标准字典接口，所以可以使用 os.environ.get(key, default)，其行为与 os.getenv() 基本一致：

import os

api_endpoint = os.environ.get("API_ENDPOINT", "https://api.example.com/v1")

3. 强制要求存在：os.environ[key]

如果你所读取的变量是程序启动的绝对先决条件（例如数据库连接串、生产环境加密私钥），一旦缺失就必须立刻报错终止，应当直接使用方括号索引 os.environ[key]。若对应键不存在，Python 会立即抛出 KeyError：

import os

try:
    secret_key = os.environ["SECRET_KEY"]
except KeyError:
    raise RuntimeError("致命错误：必须在环境变量中配置 SECRET_KEY 才能启动应用！")

4. 关键陷阱：类型转换处理

注意：从环境变量读取出的所有值始终是字符串类型（str），无论你在系统终端中配置的是数字还是布尔文本。直接用 if os.getenv("DEBUG"): 判断布尔值极易导致严重漏洞，因为字符串 "False" 或 "0" 在 Python 中均为真值。

正确转换常见数据类型的推荐写法如下：

import os

# 1. 整数与浮点数转换（带异常防护）
raw_workers = os.getenv("WORKER_COUNT", "4")
try:
    worker_count = int(raw_workers)
except ValueError:
    worker_count = 4

# 2. 布尔类型转换（正确识别常见真值文本）
raw_debug = os.getenv("DEBUG", "false")
debug_mode = raw_debug.strip().lower() in ("true", "1", "yes", "on")
print(f"Debug 模式状态: {debug_mode}")

图2：Python 读取环境变量的决策路径与类型转换步骤

三、Python 代码中怎么设置和删除环境变量

向环境变量写入数据同样通过 os.environ 进行操作。其语法就像对普通 Python 字典赋值一样直接。

1. 设置环境变量的基础语法

import os

# 设置单一环境变量
os.environ["APP_ENV"] = "production"
os.environ["LOG_LEVEL"] = "INFO"

# 验证设置结果
print(os.getenv("APP_ENV"))  # 输出: production

语法强制约束：赋给 os.environ 的键和值都必须是纯字符串（str）。如果尝试传入整数、浮点数或布尔值，例如 os.environ["TIMEOUT"] = 30，Python 会立刻抛出 TypeError: str expected, not int。正确做法是显式调用 str() 进行包装： os.environ["TIMEOUT"] = str(30)。

2. 批量设置环境变量：os.environ.update()

当需要一次性注入多个配置项时，可以使用 update() 方法传入字典：

import os

config_items = {
    "DATABASE_HOST": "127.0.0.1",
    "DATABASE_PORT": "5432",
    "CACHE_ENABLED": "true"
}

os.environ.update(config_items)

3. 删除环境变量：del 与 pop

在某些单元测试或清理场景下，你可能需要移除已有的环境变量：

import os

# 方法一：使用 del 关键字（键不存在会抛出 KeyError）
if "TEMP_TOKEN" in os.environ:
    del os.environ["TEMP_TOKEN"]

# 方法二：使用 pop() 方法（推荐，指定默认值防止报错）
removed_val = os.environ.pop("TEMP_TOKEN", None)

4. 传递给子进程示例（subprocess）

在当前 Python 脚本中用 os.environ['KEY'] = 'VAL' 修改的环境，会被后续启动的子进程自动继承。你也可以通过 subprocess.run() 显式指定定制环境：

import os
import subprocess

# 1. 方式 A：默认继承当前进程已经修改的 os.environ
os.environ["CUSTOM_FLAG"] = "ENABLED_FROM_PYTHON"
subprocess.run(["python", "-c", "import os; print(os.getenv('CUSTOM_FLAG'))"])

# 2. 方式 B：显式复制并单独定制传递给子进程，不影响当前进程环境
custom_env = os.environ.copy()
custom_env["CHILD_SPECIFIC"] = "special_value"
subprocess.run(["python", "-c", "import os; print(os.getenv('CHILD_SPECIFIC'))"], env=custom_env)

图3：设置环境变量的具体操作步骤与进程级作用域流转

四、工程化最佳实践：使用 .env 文件与 python-dotenv

在实际项目开发中，直接在代码中通过 os.environ['KEY'] = 'value' 硬编码私密配置违背了安全原则；而要求团队每位成员在命令行反复手动输入 export KEY=value 又极易遗漏。

主流做法是将本地敏感配置保存在项目根目录的 .env 文件中（加入 .gitignore 禁止提交），并利用第三方库 python-dotenv 在项目启动时将其加载到 os.environ 中。

1. 安装与配置文件编写

在终端中安装库：

pip install python-dotenv

在项目根目录创建 .env 文件：

# .env 文件示例
DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
SECRET_KEY="c8359077-secret-key-token"
DEBUG="True"
PORT=8000

2. 在代码中加载与读取

import os
from dotenv import load_dotenv

# 加载当前目录下的 .env 文件至系统环境映射中
# override=False（默认）：若系统中已存在同名环境变量，保留外部传入值
load_dotenv()

db_url = os.environ.get("DATABASE_URL")
debug_mode = os.getenv("DEBUG", "False").lower() == "true"

print(f"数据库连接地址: {db_url}")

五、全景对比与开发注意事项

为了让不同场景下的配置管理更加清晰，下表对比了主要的读写与配置方式：

机制 / 方法	典型调用代码	适用场景	核心特征与边界
os.getenv()	`os.getenv('KEY', 'def')`	读取可选配置	键不存在时返回默认值，避免程序中断
os.environ[]	`val = os.environ['KEY']`	读取核心必需配置	键不存在抛 KeyError，及早暴露配置缺失
os.environ 赋值	`os.environ['KEY'] = str(val)`	临时传递与子进程注入	仅影响当前 Python 进程及后续子进程，值必须为 str
python-dotenv	`load_dotenv()`	本地开发与密钥保护	将 .env 自动注入环境映射，代码不硬编码秘钥

图4：Python 环境变量管理生态与最佳实践全景总结

最后提醒：跨平台与安全细节

大小写敏感度差异：在 Linux 和 macOS 系统中，环境变量名称是严格区分大小写的（PORT 与 port 属于不同变量）；而在 Windows 系统中，环境变量名通常是不区分大小写的，但 Python 会保留传入时的大小写形式。编写跨平台代码时，建议统一采用全大写规范（如 DATABASE_PORT）。
敏感凭证防日志泄露：避免直接在日志中打印 print(os.environ)，这会将机器内所有凭证、Token 及敏感密码完整暴露在日志系统或终端屏幕中。如果必须记录环境上下文，应预先进行脱敏过滤。