运行Python脚本时怎么传递命令行参数

运行 Python 脚本时传递命令行参数，核心是在终端调用命令后附加用空格分隔的参数值，并在代码中通过专门的模块进行捕获。根据业务复杂度和使用场景，Python 提供了从极简内置列表到完备解析框架的多种解决方案：对于临时执行的微型脚本，可以直接使用内置的 sys.argv 列表按索引切片；对于需要健壮容错、参数提示与自动化帮助文档的正式项目，Python 官方标准库 argparse 是通用且标准的首选；而在需要构建多层级子命令或现代化类型注解支持时，第三方库如 click 与 typer 则能提供更高效率的开发体验。本文将系统拆解这几种方式的具体使用步骤、代码示例以及实战中的常见注意事项。

一、使用内置 sys.argv：最轻量的原始参数列表

在 Python 的标准库中，sys 模块提供了一个名为 argv 的字符串列表（Argument Vector）。当我们在命令行执行 Python 文件时，终端 Shell 会把整条命令按照空格进行分词，并将这些词元原封不动地存储在 sys.argv 列表中。无需安装或配置任何额外模块，只需导入 sys 即可直接读取。

# demo_sys.py
import sys

# 打印接收到的全部命令行内容
print(f"完整参数列表: {sys.argv}")

# 提取参数值（注意：第一个元素是脚本自身文件名）
script_name = sys.argv[0]
print(f"当前运行脚本: {script_name}")

if len(sys.argv) > 1:
    first_arg = sys.argv[1]
    print(f"第一个传递参数: {first_arg}")
else:
    print("未接收到任何外部参数。")

在终端中运行该脚本时，我们在文件名后面依次列出参数：

$ python demo_sys.py dev 8080
完整参数列表: ['demo_sys.py', 'dev', '8080']
当前运行脚本: demo_sys.py
第一个传递参数: dev

图 1：sys.argv 参数传递与列表索引映射原理

局限性分析：虽然 sys.argv 非常直接，但在稍微正式一点的场景下就会暴露弊端。首先，所有提取到的值都是字符串类型，即使传递的是数字 8080，也必须在代码中显式调用 int() 转换；其次，它依赖参数的绝对物理顺序，无法优雅支持 --port 8080 或 -p 8080 这样乱序的可选参数；最后，当用户少传或传错参数时，代码极易抛出 IndexError 崩溃，无法自动输出使用帮助。

二、标准库首选：使用 argparse 构建健壮命令行工具

为了解决原始切片的不足，Python 官方内置了强大的 argparse 模块。它是构建生产级命令行程序的事实标准，无需额外安装依赖，即可实现参数类型自动转换、默认值设定、互斥选项以及自动生成格式规范的 --help 帮助文档。

1. 编写 argparse 的标准四步流程

1. 导入模块：引入 Python 内置的 import argparse。
2. 创建解析器对象：实例化 argparse.ArgumentParser，可以指定程序名称与用途描述。
3. 声明参数规范：调用 add_argument() 方法，声明位置参数、短横线可选参数、参数类型、默认值以及帮助文本。
4. 触发解析：调用 parser.parse_args()，获得包含各参数属性的命名空间对象。

图 2：argparse 解析流程步骤拆解

2. 实战代码示例

下面是一个模拟数据同步服务的完整脚本，包含了位置参数、带有默认值的可选参数、类型转换以及布尔开关：

# sync_tool.py
import argparse

def main():
    # 1. 实例化解析器
    parser = argparse.ArgumentParser(
        description="数据同步服务启动工具",
        epilog="使用范例: python sync_tool.py /data/source --port 9000 --verbose"
    )

    # 2. 添加位置参数（必填项，不带前缀横杠）
    parser.add_argument("source_path", type=str, help="待同步的数据源文件路径")

    # 3. 添加可选参数（带前缀 -- 或短别名 -）
    parser.add_argument("-p", "--port", type=int, default=8000, help="监听服务端口号 (默认: 8000)")
    parser.add_argument("-e", "--env", choices=["dev", "test", "prod"], default="dev", help="运行环境")

    # 4. 添加布尔开关（flag 标记，出现即为 True）
    parser.add_argument("-v", "--verbose", action="store_true", help="是否输出详细日志")

    # 5. 执行解析
    args = parser.parse_args()

    # 6. 使用参数
    print("=== 参数解析成功 ===")
    print(f"数据源路径: {args.source_path}")
    print(f"服务端口号: {args.port} (类型: {type(args.port).__name__})")
    print(f"运行环境  : {args.env}")
    print(f"详细日志  : {args.verbose}")

if __name__ == "__main__":
    main()

3. 执行与自动帮助文档验证

在终端中，如果用户不清楚如何使用该脚本，只需附带 -h 或 --help：

$ python sync_tool.py --help
usage: sync_tool.py [-h] [-p PORT] [-e {dev,test,prod}] [-v] source_path

数据同步服务启动工具

positional arguments:
  source_path           待同步的数据源文件路径

options:
  -h, --help            show this help message and exit
  -p, --port PORT       监听服务端口号 (默认: 8000)
  -e, --env {dev,test,prod}
                        运行环境
  -v, --verbose         是否输出详细日志

使用范例: python sync_tool.py /data/source --port 9000 --verbose

当我们传入参数时，argparse 会自动校验类型。若传递非数字给 --port，它将直接输出友好的错误提示并退出，避免程序在运行深层出现不可预期的异常：

$ python sync_tool.py /var/log/app.log --port abc
usage: sync_tool.py [-h] [-p PORT] [-e {dev,test,prod}] [-v] source_path
sync_tool.py: error: argument -p/--port: invalid int value: 'abc'

三、第三方框架进阶：click 与 typer 的声明式风格

如果你的脚本正在演变为复杂的 CLI（命令行界面）产品，包含大量的子命令（如类似 git commit、git push 的嵌套结构），编写大量的 add_argument 样板代码会略显冗长。此时可以考虑现代第三方生态。

1. click：基于函数装饰器的经典之选

click 采用装饰器语法将函数直接声明为命令行接口，代码与业务逻辑结合紧密，并且对参数补全、颜色高亮等交互式终端支持极佳。

# 需要先执行: pip install click
import click

@click.command()
@click.argument("name")
@click.option("--count", default=1, help="打印次数")
def greet(name, count):
    """向指定用户打招呼的简易工具"""
    for _ in range(count):
        click.echo(f"Hello, {name}!")

if __name__ == "__main__":
    greet()

2. typer：基于 Python 现代类型注解的新一代利器

typer 是 FastAPI 作者开发的现代化 CLI 工具。它深度复用了 Python 3.6+ 的类型注解（Type Hints），无需额外定义繁杂的参数声明，函数形参即为命令行参数：

# 需要先执行: pip install typer
import typer

def main(name: str, count: int = 1, verbose: bool = False):
    """通过现代类型提示直接驱动参数解析"""
    if verbose:
        print(f"[调试模式] 即将问候 {name}")
    for _ in range(count):
        print(f"你好, {name}!")

if __name__ == "__main__":
    typer.run(main)

图 3：Python 命令行参数方案多维对比与适用场景

四、命令行传参的关键注意事项与避坑指南

1. 参数中包含空格时必须使用引号包裹

由于 Shell 默认以空格作为参数切分依据，如果参数内容本身含有空格（如文件路径 /My Documents/data.csv 或句子 Hello World），必须在命令行中使用双引号或单引号将其包含起来，否则会被系统解析为两个独立的离散参数：

# 错误传参：将被拆分为两个参数 "Hello" 与 "World"
$ python script.py Hello World

# 正确传参：被完整作为一个参数传入
$ python script.py "Hello World"

2. 布尔类型参数陷阱：不要设置 type=bool

初学者在使用 argparse 处理布尔值时，常犯的错误是声明 type=bool。在 Python 中，非空字符串转换布尔值的结果永远是 True（即 bool("False") == True）。因此，即使用户在命令行输入 --flag False，解析出来的结果依然是 True。

# 推荐做法 1：开关模式（出现该参数即为 True，不写即为 False）
parser.add_argument("--dry-run", action="store_true", help="演练模式，不实际执行修改")

# 推荐做法 2 (Python 3.9+)：自动支持 --feature 与 --no-feature
parser.add_argument("--feature", action=argparse.BooleanOptionalAction)

3. 传递变长或多个列表参数

当一个参数需要接收多个值（例如批量传入多个文件名）时，可以在 argparse 中使用 nargs 配置项：

• nargs='+'：至少需要传入 1 个值，多个值将聚合为列表。
• nargs='*'：允许传入 0 个或多个值。
• nargs=3：严格限制必须传入 3 个值。

parser.add_argument("files", nargs="+", help="传入一个或多个待处理的文件路径")
# 运行方式: python process.py file1.txt file2.txt file3.txt
# args.files 结果为: ['file1.txt', 'file2.txt', 'file3.txt']

五、方案选型决策与总结

选择何种传参方式，取决于脚本的生命周期、调用对象以及运行环境的严苛程度。以下流程决策图可帮助开发者快速确定技术路径：

图 4：Python 命令行参数方案选型决策指南

总的来说，向 Python 脚本传递命令行参数是自动化运维、数据批处理以及开发系统工具的基本技能。对于绝大多数实际生产任务，直接采用标准库 argparse 是最稳健、最符合工程规范的做法；而面对一过性的快速调试，可以直接用 sys.argv 救急；在开发面向广大终端用户的完整命令行软件时，则可以放心选用 click 或 typer 提升开发与维护体验。