python关键字参数怎么传给函数

在 Python 中，向函数传递关键字参数最直接的做法是在调用函数时使用 形参名=实参值 的形式（例如 send_email(to="user@example.com", subject="通知")），或者使用双星号 ** 将包含参数名与值的字典批量解包传入。关键字参数的核心价值在于通过指定明确的参数名称来绑定变量，调用者不需要死记形参的物理排列顺序，同时能让调用意图直观明了。本文将从基础显式传参、混合传参规则、字典解包技巧以及仅限关键字参数的约束设计四个维度，完整说明关键字参数的传递方式与避坑要点。

一、基础传参：使用“参数名=值”显式调用

在 Python 中，只要函数定义了形参，你在调用时就可以直接使用形参的名字作为键，通过赋值符号 = 传递数据。这是最常见也最直观的使用方式。

def create_user(username, email, role="member"):
    print(f"用户: {username}, 邮箱: {email}, 身份: {role}")

# 1. 完全按照形参名称传参（顺序与定义一致）
create_user(username="alex", email="alex@work.com", role="admin")

# 2. 调换传递顺序，结果完全相同
create_user(email="alex@work.com", role="admin", username="alex")

# 3. 缺省使用默认值的参数，仅指定必要关键字
create_user(username="alex", email="alex@work.com")

这里体现了关键字参数的第一个重要特性：调用顺序与函数定义顺序无关。普通的位置参数完全依赖实参在括号里的先后顺序依次装入形参槽位；而关键字参数在调用时，Python 解释器会提取出实参前的标识符，在函数的形参符号表中查找同名变量并直接绑定。只要名字拼写准确，参数写在前面还是后面都不会影响绑定结果。

二、混用传参：位置参数与关键字参数的排布法则

在实际编码中，很多函数调用会同时存在位置参数与关键字参数。混合传递必须遵循两条不可违背的铁律：

铁律 1：位置实参必须全部写在关键字实参前面

只要你的参数列表中出现了 k=v 格式的关键字实参，从该实参往后的所有实参，都必须是关键字实参。如果在关键字实参之后又写了纯位置实参，Python 解释器在语法解析阶段就会直接报错：

# 错误示例：位置实参跟在关键字实参后面
create_user(username="alex", "alex@work.com")
# 语法错误 -> SyntaxError: positional argument follows keyword argument

# 正确示例：位置实参在前，关键字实参在后
create_user("alex", email="alex@work.com", role="guest")

铁律 2：不能对同一个形参重复赋值

位置参数在执行时会最先填充前面的形参槽位。如果你已经在前序位置给第 1 个形参赋了值，紧接着又通过关键字参数显式指定了该形参的名字，Python 会报 TypeError：

# 错误示例：通过位置传入了 "alex"（占用了第1个形参 username）
# 随后又以 username="bob" 重复传值
create_user("alex", username="bob", email="alex@work.com")
# 类型错误 -> TypeError: create_user() got multiple values for argument 'username'

三、进阶传参：利用字典解包（**kwargs）动态传参

在编写自动化脚本、Web 开发或数据处理任务时，函数的参数往往来自配置文件、数据库查询或前端请求。这些数据在 Python 中天然以字典（dict）形式存在。你无需费力将字典拆开成一个个独立变量传入，使用双星号 ** 运算符即可实现一键解包：

def connect_db(host, port, username, password, database="main"):
    print(f"连接数据库 -> {username}@{host}:{port}/{database}")

# 外部配置字典
db_config = {
    "host": "127.0.0.1",
    "port": 3306,
    "username": "root",
    "password": "secret_password"
}

# 使用 ** 解包传递字典中所有的键值对
connect_db(**db_config)
# 这一句在运行时等价于：
# connect_db(host="127.0.0.1", port=3306, username="root", password="secret_password")

你还可以将字典解包与普通实参混用，或者同时解包多个字典：

base_info = {"host": "192.168.1.100", "port": 5432}
auth_info = {"username": "admin", "password": "auth_token"}

# 混用普通参数与多个字典解包
connect_db(**base_info, **auth_info, database="analytics")

如果想让函数弹性接收任何额外的关键字参数，可以在函数定义端声明 **kwargs，它会将所有多余传入的关键字参数打包成字典：

def flexible_handler(action, **kwargs):
    print(f"执行动作: {action}")
    for k, v in kwargs.items():
        print(f"  附加参数 - {k}: {v}")

flexible_handler(action="sync", timeout=30, retry=3, notify=True)

四、防护设计：仅限关键字参数（Keyword-Only Arguments）

在设计公共 API 或较复杂的业务函数时，如果某个参数是布尔开关或重要配置项，允许调用方用位置传参极易引发误解。例如 open_door(True, False, True) 没人能一眼看出每个布尔值的具体含义。

Python 3 引入了仅限关键字参数语法：在形参列表中放入一个独立的星号 *，所有位于 * 之后的参数，必须且只能使用关键字方式传递，禁止通过位置传参：

# 单星号 * 之后的 safe_mode 与 timeout 必须通过关键字传参
def export_dataset(file_path, format="csv", *, safe_mode=True, timeout=60):
    print(f"导出文件: {file_path}, 模式: {format}, 安全: {safe_mode}, 超时: {timeout}")

# 错误示例：试图以位置传参给 safe_mode 赋值
export_dataset("data.bin", "csv", False)
# 类型错误 -> TypeError: export_dataset() takes 2 positional arguments but 3 were given

# 正确示例：强制写出关键字名称，语义清晰无歧义
export_dataset("data.bin", "csv", safe_mode=False, timeout=120)

如果函数定义中已经包含可变位置参数 *args，那么紧跟在 *args 之后声明的参数也会自动变成仅限关键字参数，无需再额外添加单星号。

五、常见传参报错及排查定位

在日常使用关键字参数时，最常遇到的四类报错及其核心成因如下：

• SyntaxError: positional argument follows keyword argument：位置实参写在关键字实参后面。排查方法：检查括号内的参数排布，确保所有纯值参数移到所有 key=value 参数的前面。
• TypeError: func() got multiple values for argument 'x'：同一个形参既被位置参数占用，又被关键字参数重复赋值。排查方法：核对位置参数传入的总个数，确认是否已经把目标形参占用了。
• TypeError: func() got an unexpected keyword argument 'x'：传入的关键字名字在函数定义中不存在。排查方法：检查拼写错误，或者确认解包的字典中是否混入了未预期的多余键；若函数需要接收任意参数，应在定义中补上 **kwargs。
• TypeError: func() missing 1 required keyword-only argument: 'x'：定义了 * 之后的必要参数在调用时被遗漏，或被错误地按位置传递。排查方法：显式写出 x=value 进行调用。

六、总结速查表