在 Python 中使用环境变量：os.environ、os.environb 与跨平台考量

通过 os.environ 和 os.getenv 读取环境变量

os.environ 是一个表示进程环境的映射对象。访问一个不存在的键会引发 KeyError，而 os.environ.get(key, default) 则返回默认值。os.getenv(key, default=None) 是一个便利包装器，当变量不存在时也返回 None。关键区别在于变量未设置（返回 None）和变量设置为空字符串（返回 ''）。利用结果的真实性会将这两种状态混淆，这可能会在生产部署中无声地掩盖配置错误。

源文档指出 environ 是一个映射，其键和值都是字符串。在支持字节环境访问的平台上，可以通过 os.environb 和 os.getenvb 获取字节表示。对于大多数应用程序代码，os.environ 或 os.getenv 就足够了，因为解释器会自动处理从文件系统编码或 UTF-8 模式的解码。

import os

# Distinguish absent from empty
value = os.environ.get("APP_MODE")
if value is None:
    print("variable not set")
else:
    print("value:", repr(value))

通过 os.environ 修改和删除变量

将值赋给 os.environ[key] 会调用底层的 setenv 系统函数。删除键会调用 unsetenv。pop() 和 clear() 方法也会为每个移除的条目触发 unsetenv。这种自动同步是文档建议修改 os.environ 而不是直接调用 os.putenv 的原因，因为 putenv 写入 C 级 environ 数组而不更新 Python 映射，导致 os.environ 过时。在某些平台上，包括 FreeBSD 和 macOS，重复调用 setenv 或 putenv 可能会导致 C 运行时中的内存泄漏。这是一个平台级别的问题而非 Python 错误，但这意味着频繁修改环境变量的长运行进程应尽量减少创建的键的数量。

import os

os.environ["APP_MODE"] = "production"  # calls setenv
os.environ.pop("APP_MODE", None)       # calls unsetenv if present

os.environ 和 os.environb 的同步

os.environb 是一个字节版本的映射，仅在 os.supports_bytes_environ 为 True 时可用，这在 Unix 平台上成立。这两个映射保持同步：修改 environb 会更新 environ，反之亦然。这意味着你可以向 environb 写入字节值并从 environ 读取解码后的字符串，或者相反。在 Windows 上，supports_bytes_environ 为 False 且不存在 environb，因此针对两个平台的代码必须使用该标志保护访问。同步使用文件系统编码及其错误处理器在字节和 str 之间进行转换。如果字节值包含在当前编码下无法解码的序列，surrogateescape 会在 str 视图中产生孤立的代理字符。通过两种表示形式进行往返传输可以保留原始字节。

import os

if os.supports_bytes_environ:
    os.environb[b"RAW_KEY"] = b"\xff\xfe"
    print(os.environ["RAW_KEY"])  # decoded via fsencode/fsdecode

编码：UTF-8 模式、fsencode/fsdecode 和 getenvb

当 Python UTF-8 模式激活时（通过 -X utf8 或 PYTHONUTF8=1 启用，或在区域设置为 C 或 POSIX 时自动启用），环境变量无论系统区域如何都使用 UTF-8 进行解码。在 UTF-8 模式之外，文件系统编码控制解码。os.fsencode 和 os.fsdecode 显式暴露这些转换，是处理可能出现在环境变量值中的路径类字节的推荐方式。os.getenvb 返回环境变量的原始字节，不进行任何解码步骤。这对于检查或转发可能包含当前编码无效字节值的情况很有用，或者编写必须避免隐式解码再重编码往返过程的便携代码。

import os, sys

print("filesystem encoding:", sys.getfilesystemencoding())
print("utf8 mode:", sys.flags.utf8_mode)

# Raw bytes access (Unix only)
if os.supports_bytes_environ:
    raw = os.getenvb(b"LANG")
    print("LANG bytes:", raw)

环境缓存和 os.reload_environ

文档明确指出：os.environ 和 os.environb 是 Python 启动时环境变量的缓存。在解释器外部或通过 os.putenv 和 os.unsetenv 进行的更改不会反映在映射中。os.reload_environ 于 Python 3.14 添加，用于从当前进程环境刷新两个映射。在 3.14 之前，没有标准机制可以在外部修改后重新同步缓存。这在父进程或信号处理程序通过 C 级 API 修改环境，或库调用 putenv 而不经过 os.environ 的情况下很重要。如果没有 reload_environ，随后的读取将返回过时的值。

import os

# After external modification of the process environment:
os.reload_environ()  # Python 3.14+
print(os.environ.get("EXTERNALLY_SET_VAR"))

操作环境时的错误和线程安全性

os 模块中的所有函数在参数类型正确但被操作系统拒绝时都会抛出 OSError 或其子类。对于环境操作来说这种情况很少见，因为 setenv 和 unsetenv 对有效字符串都能成功，但键或值中的无效代理字符可能在到达系统调用之前触发 UnicodeEncodeError。os.reload_environ 带有明确的警告，说明它不是线程安全的。在重载进行时从 os.environ、os.environb 读取或调用 os.getenv 可能会返回空结果。在多线程应用程序中，序列化对 reload_environ 的访问或完全避免它，仅通过 os.environ 突变来管理环境状态。

import os

try:
    os.environ["BAD_KEY"] = "value\ud800"  # lone surrogate
except UnicodeEncodeError as e:
    print("encoding error:", e)

跨平台可移植性：os.name、平台限制和 PATH

os.name 在类 Unix 系统上返回 'posix'，在 Windows 上返回 'nt'。在 WebAssembly、Android 和 iOS 上，os 模块的大部分不可用或行为不同：fork、execve 和 spawn 等进程 API 缺失，getuid 和 getpid 可能是桩函数。必须在这些目标上运行的代码应在依赖特定平台行为之前检查 os.name 和 os.supports_bytes_environ。os.get_exec_path 返回搜索可执行文件的目录列表，从提供的 env 字典或默认的 os.environ 中读取 PATH 变量。这是 shell PATH 查找的程序化等效物，并在 spawn 和 exec 函数的 p 变体内部使用。

import os

print("os.name:", os.name)
print("supports_bytes_environ:", os.supports_bytes_environ)
print("exec paths:", os.get_exec_path())

通过 spawn 和 exec 将环境传递给子进程

spawn*e 和 exec*e 变体接受一个 env 参数，该参数完全替换子进程的环境，而不是从父进程继承。此映射中的键和值必须是字符串；无效类型会导致函数失败并返回 127。当提供 env 时，可执行文件的 PATH 查找使用新环境，而不是父进程的 os.environ。继承（spawnl, spawnv, execl, execv）和替换（spawnle, spawnlpe, spawnve, spawnvpe, execle, execvpe）之间的区别对于沙箱子进程或注入配置而不污染父环境至关重要。

import os

child_env = dict(os.environ)
child_env["APP_MODE"] = "production"
# spawnvpe replaces the child environment entirely
status = os.spawnvpe(os.P_WAIT, "cp", ["cp", "index.html", "/dev/null"], child_env)
print("exit status:", status)