Python脚本如何读取本地JSON配置

wen python案例 2026-06-27 28

Python脚本高效读取本地JSON配置：从入门到最佳实践

目录导读

为什么选择JSON作为配置文件格式？
核心方法：Python内置json模块完整用法
进阶技巧：处理编码、异常与路径问题
实战案例：读取多层级嵌套配置
常见问题FAQ（问答环节）
总结与推荐实践路径

为什么选择JSON作为配置文件格式？

在Python项目开发中，配置管理是核心环节，JSON（JavaScript Object Notation）凭借以下优势成为主流选择：

Python脚本如何读取本地JSON配置

跨语言兼容：几乎所有编程语言都支持解析JSON
可读性强：键值对结构清晰，支持嵌套和数组
标准库支持：Python内置json模块，零依赖即可完成读写
类型映射自然：JSON的字符串、数字、布尔、数组、对象直接对应Python的str、int/float、bool、list、dict

一个典型的本地JSON配置示例（config.json）：

{
    "database": {
        "host": "localhost",
        "port": 3306,
        "username": "admin",
        "password": "encrypted_pass"
    },
    "api_keys": ["key1", "key2"],
    "debug_mode": false,
    "max_connections": 50
}

与其他格式对比：

INI文件：结构简单但缺乏嵌套支持
YAML：语法灵活但需要第三方库（PyYAML）
环境变量：适合敏感信息但缺乏结构化

核心方法：Python内置json模块完整用法

1 基础读取流程（标准写法）

import json
import os
def load_config(config_path):
    """安全加载JSON配置文件"""
    # 验证文件是否存在
    if not os.path.exists(config_path):
        raise FileNotFoundError(f"配置文件 {config_path} 未找到")
    # 使用with语句自动管理文件资源
    with open(config_path, 'r', encoding='utf-8') as f:
        try:
            config = json.load(f)  # 核心解析方法
        except json.JSONDecodeError as e:
            raise ValueError(f"JSON格式错误: {e}")
    return config
# 使用示例
config = load_config('config.json')
print(config['database']['host'])  # 输出: localhost

2 关键参数说明

参数	作用	默认值
`encoding='utf-8'`	避免中文乱码	系统默认编码
`strict=False`	允许控制字符	True
`parse_constant`	处理JSON特殊值	默认解码`NaN`等

3 一行代码读取（生产环境慎用）

config = json.load(open('config.json', 'r', encoding='utf-8'))

缺点：未关闭文件句柄,存在资源泄漏风险。

进阶技巧：处理编码、异常与路径问题

1 文件路径最佳实践

相对路径 vs 绝对路径：

import sys
import os
# 获取脚本所在目录（推荐）
script_dir = os.path.dirname(os.path.abspath(__file__))
config_path = os.path.join(script_dir, 'config.json')
# 使用pathlib（Python 3.4+）
from pathlib import Path
config_path = Path(__file__).parent / 'config.json'

2 异常处理完整框架

def safe_load_json(filepath):
    """健壮的JSON加载器"""
    try:
        with open(filepath, 'r', encoding='utf-8') as f:
            return json.load(f)
    except FileNotFoundError:
        print(f"[错误] 配置文件不存在: {filepath}")
        # 可返回默认配置或退出
        return get_default_config()
    except PermissionError:
        print(f"[错误] 无读取权限: {filepath}")
        raise
    except UnicodeDecodeError:
        print(f"[错误] 文件编码异常，需检查是否为UTF-8")
        # 尝试其他编码
        with open(filepath, 'r', encoding='gbk') as f:
            return json.load(f)
    except json.JSONDecodeError as e:
        print(f"[错误] JSON语法错误: {e.msg}, 位置: {e.lineno}:{e.colno}")
        raise

3 处理JSON特殊值

# 处理NaN、Infinity等非标准值
with open('config.json', 'r') as f:
    data = json.load(f, parse_constant=lambda x: None)  # 将NaN转为None

实战案例：读取多层级嵌套配置

1 复杂配置结构示例

{
    "services": {
        "web": {
            "host": "0.0.0.0",
            "port": 8080,
            "ssl": {
                "enabled": true,
                "cert_path": "/etc/ssl/server.crt"
            }
        },
        "database": {
            "primary": {
                "dsn": "mysql://localhost:3306/db",
                "pool_size": 20
            },
            "replicas": [
                {"host": "replica1.example.com", "port": 3306},
                {"host": "replica2.example.com", "port": 3307}
            ]
        }
    }
}

2 安全读取嵌套值

def get_nested_value(config, keys, default=None):
    """安全获取嵌套配置值，避免KeyError"""
    result = config
    for key in keys:
        if isinstance(result, dict) and key in result:
            result = result[key]
        else:
            return default
    return result
# 使用示例
config = load_config('complex_config.json')
ssl_port = get_nested_value(config, ['services', 'web', 'port'], 80)
replica_hosts = get_nested_value(config, ['services', 'database', 'replicas'], [])

3 使用`get`方法替代直接索引

web_config = config.get('services', {}).get('web', {})
ssl_enabled = web_config.get('ssl', {}).get('enabled', False)

常见问题FAQ（问答环节）

Q1：读取配置时出现json.decoder.JSONDecodeError: Expecting ',' delimiter怎么办？ A：检查JSON文件最后是否有多余逗号（如{"key": "value",}），或字符串未正确转义，推荐用在线JSON格式化工具（如jsonlint）验证文件。

Q2：配置文件中包含中文字符，读取后乱码？ A：确保在open()时指定encoding='utf-8'，并且JSON文件本身以UTF-8格式保存,在Windows下需注意文件保存编码。

Q3：如何支持读取用户家目录下的配置文件（如~/.config.json）？ A：使用os.path.expanduser('~/.config.json')自动扩展符号。

Q4：多线程环境下读取配置文件需要注意什么？ A：JSON文件加载属于I/O操作，建议在主线程初始化时一次性加载到内存，后续通过只读方式访问，若需热更新,需加读写锁。

Q5：能否让Python脚本自动检测配置文件位置？ A：实现优先级策略：1) 命令行参数指定路径 2) 环境变量CONFIG_PATH 3) 当前目录下的config.json 4) 预设默认路径。

总结与推荐实践路径

通过本文,您已掌握：

基础语法：用json.load()读取本地配置
健壮处理：异常捕获、编码管理、路径解析
高级技巧：嵌套值安全访问、默认值回退
生产建议：资源管理、跨平台路径、多格式兼容

推荐配置架构：

项目根目录/
├── src/
│   └── main.py
├── config/
│   ├── default.json       # 默认配置
│   ├── production.json    # 生产环境覆盖
│   └── local.json         # 本地开发覆盖（git忽略）
└── your_script.py

进阶学习方向：