VS Code 运行 Python 脚本时怎么传入命令行参数

一、核心机制：命令行参数如何流入 Python 脚本

编写脚本时，程序通常通过标准库的 sys.argv 列表或 argparse 模块捕获外部输入的参数。无论在系统控制台还是在 VS Code 中，底层都是由一个进程（VS Code 或终端宿主）调用 Python 解释器可执行文件，并将一系列以空格分隔的字符串打包传递给解释器。

为了便于后续验证，先准备一个通用的测试脚本 main.py，用于打印捕获到的参数：

import sys
import argparse

def main():
    print(f"原始 sys.argv 内容: {sys.argv}")
    
    parser = argparse.ArgumentParser(description="VS Code 参数传递测试")
    parser.add_argument("--mode", type=str, default="train", help="运行模式")
    parser.add_argument("--epochs", type=int, default=10, help="迭代轮数")
    parser.add_argument("--input-file", type=str, help="输入文件路径")
    
    args = parser.parse_args()
    print(f"解析后的参数对象: mode={args.mode}, epochs={args.epochs}, input_file={args.input_file}")

if __name__ == "__main__":
    main()

图 1：VS Code 传参到 Python 解释器及脚本内部的数据流向

二、方法一：配置 launch.json 调试文件（推荐标准做法）

当需要在代码中打断点、逐步观察变量，同时又依赖命令行参数时，配置 launch.json 是最方便、最标准的方法。该文件保存在项目根目录下的 .vscode/launch.json 中。

1. 操作步骤

1. 打开调试视图：点击 VS Code 左侧活动栏的“运行和调试”图标（或按快捷键 Ctrl+Shift+D / Cmd+Shift+D）。
2. 创建 launch.json：如果项目中尚未创建该文件，点击面板上方的“创建 launch.json 文件”，在下拉列表中选择“Python 调试程序（Python Debugger）”，再选择“Python 文件（Python File）”。
3. 添加 args 属性：在生成的配置项中，添加 "args": [...] 字段，将需要传递的参数以字符串数组的形式写入。
4. 启动运行：保持当前编辑器聚焦在 Python 文件上，按 F5 或点击调试面板左上角的绿色播放按钮即可带参启动。

图 2：launch.json 从配置到运行的四步操作流程

2. launch.json 配置代码示例

打开项目根目录下的 .vscode/launch.json，按如下结构编写配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: 带参数运行当前文件",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": [
        "--mode", "eval",
        "--epochs", "25",
        "--input-file", "data/test_samples.json"
      ]
    }
  ]
}

三、launch.json 中 args 数组的书写规则与避坑要点

在实际操作中，很多初学者传入参数后程序报错，往往不是代码问题，而是对 args 的格式理解有偏差。

1. 必须拆分为独立项，切勿整串合并

命令行中习惯输入 --epochs 50，但在 JSON 的 args 数组里，参数标志与参数值必须拆分成独立的字符串元素。如果写成 ["--epochs 50"]，系统会把 --epochs 50 整体作为一个参数传递给 Python，argparse 会因为无法识别带空格的选项名而直接抛出 unrecognized arguments 异常。

2. 包含空格的路径无需手动加转义引号

如果文件路径包含空格（例如 my data/test.csv），在终端命令中通常需要手动加双引号。而在 launch.json 的 args 数组中，每一项本身就是一个独立参数，VS Code 会在组装终端命令时自动处理转义，直接写 "my data/test.csv" 即可，千万不要手动套一层转义双引号。

图 3：args 数组中推荐规范与常见误区对比

四、方法二：在 VS Code 内置集成终端中直接运行

如果不涉及复杂的断点调试，或者参数每次都在频繁改动，直接使用 VS Code 内置的集成终端（Integrated Terminal）是最直观的方案。

操作流程

1. 使用快捷键 Ctrl+`（反引号）或通过顶部菜单“终端” > “新建终端”调出控制台。
2. 确认当前终端处于正确的 Python 虚拟环境（终端提示符通常会显示环境名，例如 (.venv)）。
3. 直接输入常规 Python 命令执行脚本并追加参数：

# 示例命令
python main.py --mode eval --epochs 30 --input-file data/val.json

五、方法三：配置 tasks.json 自定义任务（进阶场景）

如果需要在执行 Python 脚本前先执行其他构建命令（例如先拉取数据、再清洗、再运行训练），或者希望通过快捷键一键执行带有预设参数的命令而无需打开调试器，可以使用 VS Code 的任务系统（Tasks）。

在 .vscode/tasks.json 中添加如下配置：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "运行 Python 数据处理",
      "type": "shell",
      "command": "python",
      "args": [
        "main.py",
        "--mode", "clean",
        "--epochs", "5"
      ],
      "group": {
        "kind": "build",
        "isDefault": true
      },
      "presentation": {
        "echo": true,
        "reveal": "always",
        "panel": "shared"
      }
    }
  ]
}

配置完成后，按下 Ctrl+Shift+B（Mac 上为 Cmd+Shift+B）即可直接运行该任务，输出结果会展示在集成终端面板中。

六、三种传参方案对比与选型建议

不同场景下的需求不同，合理选用对应的传参方式可以大幅节省调试和运行时间：

图 4：VS Code 传入参数的三种方案核心特性与决策矩阵

七、常见排查与实用技巧

1. 修改 launch.json 后按 F5 依然执行旧参数？

请检查顶部调试下拉菜单中选中的配置名称。如果在 launch.json 中定义了多个配置（例如分别配置了“训练模式”和“验证模式”），需要确认调试启动下拉框选中的配置项名称与当前修改的项完全一致。

2. 如何支持交互式动态输入参数？

如果希望每次点击调试时，VS Code 弹出一个输入框询问当前参数，可以利用 VS Code 的 inputs 变量：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "动态输入参数运行",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": [
        "--mode", "${input:selectMode}"
      ]
    }
  ],
  "inputs": [
    {
      "id": "selectMode",
      "type": "pickString",
      "description": "请选择当前运行模式",
      "options": ["train", "eval", "predict"],
      "default": "train"
    }
  ]
}

这样配置后，每次启动调试都会在编辑器顶部弹出选择列表，兼具了图形化交互的便捷与命令行参数的灵活性。