用 `configparser` 优雅管理 Python 应用配置，这几个坑你得知道

69次阅读

共计 9330 个字符，预计需要花费 24 分钟才能阅读完成。

以前刚写一些自动化脚本或小工具的时候，图省事总是把数据库连接字符串、API 密钥，甚至是一些关键路径直接硬编码在 Python 文件里。每次环境一变，比如从开发环境部署到测试环境，或者换个服务器，就得手动改代码，然后重新打包部署，费时又容易出错。最惨的一次是，线上服务因为一个配置文件里的路径写死，结果部署时路径稍有变动，服务直接报错崩了，排查了半天，才意识到配置管理的重要性。

所以，今天想跟大家聊聊 Python 里如何优雅地管理这些应用程序的配置。我个人摸索了几年，试过直接用字典、手动解析文本，但最终还是发现 Python 标准库里的 configparser 对处理常见 INI 格式的配置最省心，也最健壮。它能帮你告别硬编码的窘境，让你的应用更灵活，更易维护。

INI 文件是一种非常简单直观的文本格式，用于存储应用程序的配置信息。它的核心结构就是“节”（Section）和“键值对”（Key-Value Pair）。

一个典型的 INI 文件长这样：

; 这是一个配置文件示例
[server]
host = 127.0.0.1
port = 8080
debug_mode = yes
max_connections = 100

[database]
type = postgresql
user = admin
password = mysecretpassword
host = db.example.com
port = 5432
schema = public

[paths]
log_dir = /var/log/myapp
data_dir = /opt/myapp/data
temp_dir = %(data_dir)s/temp ; 这里演示了插值用法，它会引用同配置器中的 data_dir

小提醒：

[] 包裹的是 Section 名称，它把相关的配置项分组。
key = value 是键值对，等号两边可以有空格，configparser 会自动处理。
分号 ; 或井号 # 开头的是注释行，configparser 读取时会忽略。
INI 文件是扁平化的，不能像 YAML 或 JSON 那样表达复杂的嵌套结构。如果你的配置结构极其复杂，可能需要考虑其他格式。

有了配置文件，接下来就是如何在 Python 程序里读取它。configparser 的读取过程非常直接。

import configparser
import os

# 实例化一个 ConfigParser 对象
config = configparser.ConfigParser()

# 定义配置文件路径
# 我平时习惯将配置文件放在脚本同级目录或一个固定的 config 目录下
# 这样部署到不同环境时，只需确保配置文件在相对位置即可，不容易出错。config_file_path = 'config.ini'

# 检查文件是否存在，避免程序因文件不存在而意外退出
if not os.path.exists(config_file_path):
    print(f"配置文件'{config_file_path}'不存在，请检查！")
    # 这里可以根据实际情况选择是退出程序，还是使用默认配置
    exit(1)

# 读取配置文件
# 亲测，加 encoding='utf-8' 能避免一些中文配置值可能导致的乱码问题
try:
    config.read(config_file_path, encoding='utf-8')
except configparser.MissingSectionHeaderError as e:
    print(f"配置文件格式错误：{e}")
    exit(1)

print("--- 读取 [server] 配置 ---")
# 获取字符串类型的值
host = config.get('server', 'host')
port_str = config.get('server', 'port') # 注意：get 默认返回的是字符串
debug_mode_str = config.get('server', 'debug_mode')

print(f"Server Host: {host}")
print(f"Server Port ( 字符串): {port_str}")
print(f"Debug Mode ( 字符串): {debug_mode_str}")

# 获取特定数据类型的值
# 刚开始用的时候总忘记转类型，直接拿字符串去连接数据库就报错了，多亏同事指点，# configparser 提供了 getint, getfloat, getboolean 这些方便的方法
port = config.getint('server', 'port')
debug_mode = config.getboolean('server', 'debug_mode')
max_connections = config.getint('server', 'max_connections')

print(f"Server Port ( 整数): {port}")
print(f"Debug Mode ( 布尔): {debug_mode}")
print(f"Max Connections ( 整数): {max_connections}")

print("n--- 读取 [database] 配置 ---")
db_type = config.get('database', 'type')
db_user = config.get('database', 'user')
db_password = config.get('database', 'password')
# 如果某个选项可能不存在，可以用 fallback 参数提供默认值，避免 KeyError
db_schema = config.get('database', 'schema', fallback='default_schema')
print(f"Database Type: {db_type}")
print(f"Database User: {db_user}")
print(f"Database Password: {db_password}")
print(f"Database Schema ( 带 fallback): {db_schema}")

# 获取某个 Section 下的所有键值对
print("n--- 获取 [database] 所有配置 ---")
for key, value in config.items('database'):
    print(f"{key} = {value}")

# 访问插值后的路径
print("n--- 访问 [paths] 配置 ---")
log_dir = config.get('paths', 'log_dir')
data_dir = config.get('paths', 'data_dir')
temp_dir = config.get('paths', 'temp_dir') # 经过插值后，它会是 /opt/myapp/data/temp
print(f"Log Directory: {log_dir}")
print(f"Data Directory: {data_dir}")
print(f"Temp Directory ( 插值后): {temp_dir}")

小提醒：

config.read() 方法本身在文件不存在时不会抛出异常，而是返回一个空列表。所以，在调用 get() 系列方法之前，最好先用 os.path.exists() 检查文件是否存在，或者捕获 NoSectionError 和 NoOptionError。
config.get() 默认返回字符串。对于数字（整数、浮点数）和布尔值，请务必使用 getint(), getfloat(), getboolean() 进行类型转换，否则在后续计算或逻辑判断中会遇到类型错误。

很多时候，我们的应用需要动态调整配置，比如改变日志级别、切换数据库连接，或者在程序运行时更新某些参数。configparser 也支持这些操作。

import configparser
import os

config = configparser.ConfigParser()
config_file_path = 'config.ini'
config.read(config_file_path, encoding='utf-8')

print("--- 原始配置 (port) ---")
print(f"Server Port: {config.getint('server','port')}")

# 修改现有配置项
# 之前做 A / B 测试切换 IP 时，就用这种方式动态修改配置，不需要重启整个服务
config.set('server', 'port', '8888')
config.set('server', 'host', '192.168.1.100')

# 添加新的配置项
config.set('server', 'new_feature_flag', 'true')

# 添加新的 Section
if not config.has_section('logging'):
    config.add_section('logging')
config.set('logging', 'level', 'INFO')
config.set('logging', 'file', '/tmp/app.log')

print("n--- 修改后配置 (port) ---")
print(f"Server Port: {config.getint('server','port')}")
print(f"Server Host: {config.get('server','host')}")
print(f"New Feature Flag: {config.getboolean('server','new_feature_flag')}")
print(f"Logging Level: {config.get('logging','level')}")


# 删除配置项或 Section
# config.remove_option('server', 'max_connections') # 假设我们想删除这个
# config.remove_section('database') # 假设我们想删除整个数据库配置

# 将修改后的配置写回文件
# 注意：write() 会覆盖原有文件内容。我个人会习惯先备份原始文件，或者写到另一个文件中
# with open('config_updated.ini', 'w', encoding='utf-8') as f:
#     config.write(f)
# print("n 配置已保存到 config_updated.ini")

# 为了演示，我们先不实际写入文件，以免覆盖掉原始示例
print("n 配置已在内存中修改，若需持久化请取消注释 write 方法。")

print("n--- 所有 Section ---")
print(config.sections())
print("n--- [logging] 所有配置 ---")
for key, value in config.items('logging'):
    print(f"{key} = {value}")

小提醒：

config.set() 方法如果对应的 Section 或 Option 不存在，它会自动创建。
config.write(file_object) 方法会将当前 ConfigParser 对象中的所有配置写入到指定的文件对象中。 请注意，这会覆盖文件原有内容！ 在生产环境中，如果你需要更新部分配置，一个更稳妥的做法是：读取现有配置 -> 在内存中修改 -> 将整个修改后的配置写回文件。
has_section() 和 has_option() 在操作前检查 Section 或 Option 是否存在非常有用，可以避免一些不必要的错误。

configparser 不仅支持文件内部的插值，还可以利用 DEFAULT Section 来设置全局默认值，以及通过 ConfigParser 的构造函数集成环境变量，这在多环境部署时非常有用。

import configparser
import os

# 定义一个包含默认值的配置文件
# DEFAULT Section 是一种特殊 Section，它的键值可以在其他 Section 中被引用
# 同时，如果其他 Section 中没有某个键，但 DEFAULT 中有，也会被引用
# 这是一个非常实用的功能，比如可以定义所有环境通用的配置
default_ini_content = """
[DEFAULT]
app_name = MyApp
log_level = INFO
base_path = /tmp/app

[server]
host = 127.0.0.1
port = 8080
log_level = DEBUG ; 覆盖了 DEFAULT 中的 log_level

[database]
type = sqlite
path = %(base_path)s/db.sqlite
"""

# 将默认内容写入一个临时文件
with open('default_config.ini', 'w', encoding='utf-8') as f:
    f.write(default_ini_content)

# 实例化 ConfigParser，并设置 allow_no_value 为 True 以支持没有值的键
# 这里通过 defaults 参数可以预设一些默认值，优先级低于 INI 文件中的 DEFAULT Section
# 另外，ConfigParser(interpolation=configparser.ExtendedInterpolation()) 可以支持更复杂的插值，比如引用环境变量
config = configparser.ConfigParser(defaults={'env_user': os.environ.get('USER', 'unknown_user')},
    interpolation=configparser.ExtendedInterpolation() # 支持环境变量插值)

config.read('default_config.ini', encoding='utf-8')

print("--- 访问带 DEFAULT 和 Environment 变量的配置 ---")

# 访问 DEFAULT 中的值
app_name = config.get('server', 'app_name')
print(f"App Name ( 来自 DEFAULT): {app_name}")

# Section 内部的键会覆盖 DEFAULT 中的同名键
server_log_level = config.get('server', 'log_level')
print(f"Server Log Level ( 覆盖 DEFAULT): {server_log_level}")

# 数据库路径使用了 DEFAULT 中的 base_path 进行插值
db_path = config.get('database', 'path')
print(f"Database Path ( 插值): {db_path}")

# 访问通过 defaults 参数设置的默认值（来自环境变量）env_user = config.get('DEFAULT', 'env_user') # DEFAULT section 可以直接访问通过 defaults 传入的参数
print(f"Environment User ( 通过 defaults 参数传入): {env_user}")

# 进一步演示 ExtendedInterpolation 引用环境变量
# 假设我们有一个配置需要根据环境变量 HOME 来决定路径
print("n--- 演示 ExtendedInterpolation 引用环境变量 ---")
os.environ['MY_APP_ROOT'] = '/opt/my_custom_app_root' # 临时设置一个环境变量

env_interpolation_config_content = """
[settings]
root_path = ${MY_APP_ROOT}/data
"""with open('env_interpolation_config.ini','w', encoding='utf-8') as f:
    f.write(env_interpolation_config_content)

env_config = configparser.ConfigParser(interpolation=configparser.ExtendedInterpolation())
env_config.read('env_interpolation_config.ini', encoding='utf-8')

root_path = env_config.get('settings', 'root_path')
print(f"Root Path ( 引用环境变量 MY_APP_ROOT): {root_path}")

# 清理临时文件和环境变量
os.remove('default_config.ini')
os.remove('env_interpolation_config.ini')
del os.environ['MY_APP_ROOT']

小提醒：

DEFAULT Section 的配置项在任何其他 Section 中都可以被引用，且如果其他 Section 没有定义某个键，会自动去 DEFAULT 中查找。这在设置全局默认值时非常方便。
interpolation=configparser.ExtendedInterpolation() 是一个强大功能，它允许你使用 ${VAR_NAME} 语法来引用环境变量，极大地增强了配置的灵活性和跨环境适应性。我以前部署在不同环境，就靠这个来兼容，省得为每个环境都写一个 ini 文件。

在日常开发中，我发现不少 Python 初学者在使用 configparser 时，很容易掉进一些相似的坑里。这里给大家总结几个我当年也踩过、或看同事踩过的“坑”，希望能帮助大家避开。

误区一：数据类型未转换就直接使用

这是最常见也最隐蔽的坑。configparser 的 get() 方法，无论是获取数字、布尔值还是其他任何内容，它统一返回的都是字符串。

新手常犯：

port_str = config.get('server', 'port') # 假设 'port' 是 '8080'
# db_connection(host, port_str) # 直接用字符串 '8080' 去连接，结果报类型错误或端口无法识别
if config.get('server', 'debug_mode') == 'True': # 错误判断，因为 'True' 是字符串，而 Python 的 True 是布尔值
    print("Debug mode is ON")

我的经验： 刚开始学的时候，拿到一个 port 配置，直接拿 str 去 int() 转换，或者用 debug_mode 的字符串 'True' 去做 if 判断，结果都出错了，排查半天发现是类型不匹配。configparser 已经为我们提供了 getint(), getfloat(), getboolean() 等方法，直接用它们就能避免这种低级错误。

正确做法：

port = config.getint('server', 'port')
debug_mode = config.getboolean('server', 'debug_mode') # 会自动识别 'yes', 'no', 'true', 'false', '1', '0' 等
if debug_mode:
    print("Debug mode is ON (correctly parsed)")

误区二：配置文件路径处理不当

很多开发者在本地开发时习惯将配置文件放在脚本同级目录，或者直接写死一个绝对路径。但当项目部署到不同操作系统或不同环境中时，这些硬编码的路径就成了定时炸弹。

新手常犯：

config_file = 'my_app_config.ini' # 假设脚本当前运行目录就是配置文件所在目录
# config_file = '/home/user/my_app/config.ini' # 硬编码绝对路径
config.read(config_file)

我的经验： 刚接手一个项目，配置文件路径写死在 C:config.ini，结果部署到 Linux 上直接崩了，因为它根本找不到这个路径。更常见的，一些自动化脚本在不同目录执行时，相对路径就会失效。

正确做法：

使用 os.path.join 和 os.path.dirname(__file__) 构造基于脚本所在目录的相对路径。 这种方法最常用且稳健。

import os
current_dir = os.path.dirname(os.path.abspath(__file__)) # 获取当前脚本的绝对路径
config_file = os.path.join(current_dir, 'config', 'my_app_config.ini') # 假设配置文件在脚本同级的 config 目录下
config.read(config_file)

从命令行参数或环境变量中获取配置路径。 适合大型或需要高度定制部署的应用。

误区三：默认值的处理不够优雅

在读取配置时，有些配置项可能不是每次都必须存在的，或者在不存在时需要一个合理的默认值。新手往往会用繁琐的 try-except 或 if-else 来判断。

新手常犯：

# 方式一：用 try-except
try:
    timeout = config.getint('network', 'timeout')
except (configparser.NoOptionError, ValueError):
    timeout = 30 # 设置默认值

# 方式二：用 if-else (先检查是否存在)
if config.has_option('network', 'retries'):
    retries = config.getint('network', 'retries')
else:
    retries = 3 # 设置默认值

我的经验： 早期项目里，我每次取配置都写一大堆 if else 来判断有没有值，代码冗余且可读性差，改动一个配置项就得检查好几处。直到后来发现 get() 方法的 fallback 参数，瞬间清爽了不少。
正确做法：
- 使用 get() 方法的 fallback 参数。
```
timeout = config.getint('network', 'timeout', fallback=30)
retries = config.getint('network', 'retries', fallback=3)
```
- 利用 DEFAULT Section。 如果是通用的默认值，可以直接放在 [DEFAULT] Section 里。