别再手敲命令了：VS Code 调试配置 (launch.json) 终极指南

发表于 分类于 ， 本文字数： 1.7k 6 mins

说实话，每次看到有人在终端里一遍遍手敲 python manage.py runserver，或者为了看个变量值到处插 print()，我都替他累。

VS Code 明明自带了强大的调试器，为什么不用？多半是被 launch.json 那个看起来有点复杂的配置文件劝退了。

今天咱们就把它拆解开，让你彻底告别低效的“人肉调试”。

目录

  1. 为什么要折腾 launch.json？
  2. 这就去创建你的第一个配置
  3. 参数详解：别被 JSON 吓到了
  4. 环境变量：别再手动 set 了
  5. 进阶玩法：用户输入与多环境
  6. 调试技巧：除了 F5 还能干啥
  7. 避坑指南：那些年我踩过的坑
  8. Web 框架特供：Django & Flask

1. 为什么要折腾 launch.json？

你可能会问：“我直接在终端运行不香吗？”

香，直到你遇到这些情况：

  • 环境变量地狱：项目依赖 DATABASE_URL、API_KEY，每次开新终端都要重新 export 或 set 一遍，烦不烦？
  • 参数记忆大师：运行脚本需要带一堆参数 --mode dev --config ./conf/local.yaml --verbose，少敲一个就报错。
  • Print 调试法：为了看一个变量，改代码加 print，运行看结果，然后再删掉 print。如果不小心把 print 提交到生产环境……画面太美。

launch.json 就是你告诉 VS Code “该怎么运行我的代码” 的说明书。配置一次，以后只需要按一下 F5，环境变量自动加载，参数自动带上，断点随你打。

2. 这就去创建你的第一个配置

别想太复杂，VS Code 的调试配置主要就存在 .vscode/launch.json 里。

最快上手姿势：

  1. 点击左侧活动栏的「运行和调试」图标（或者直接 Ctrl+Shift+D）。
  2. 点击「创建 launch.json 文件」。
  3. 选择你的语言（比如 Python）。

VS Code 会自动给你生成一个基础模板。

3. 参数详解：别被 JSON 吓到了

打开 launch.json，你可能会看到一堆参数。其实常用的就那几个，我把它们翻译成“人话”：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
    "version": "0.2.0",
    "configurations": [
        {
            // ===== 给人看的 =====
            "name": "启动我的程序",          // 调试菜单里显示的名字，起个自己看得懂的
            
            // ===== 给 VS Code 看的 =====
            "type": "debugpy",               // 调试器类型，Python 就填这个
            "request": "launch",             // 模式：launch (启动新程序) 或 attach (附加到已运行程序)
            
            // ===== 核心配置 =====
            "program": "${workspaceFolder}/src/main.py",  // 入口文件。${workspaceFolder} 是你的项目根目录
            "args": ["--mode", "dev"],       // 相当于在命令行里敲的参数
            "cwd": "${workspaceFolder}",     // "Current Working Directory"，程序运行时的“当前目录”
            
            // ===== 调试行为 =====
            "console": "integratedTerminal", // 推荐用这个！使用 VS Code 自带的终端，支持输入和颜色
            "justMyCode": true               // true: 只调试你的代码；false: 连第三方库源码一起调试（比如想看 Django 源码时用）
        }
    ]
}

几个关键变量

VS Code 提供了一些变量，不用死记硬背，混个眼熟就行：

  • ${workspaceFolder}：项目根目录（最常用）。
  • ${file}：你当前打开的那个文件。如果你想“运行当前文件”，就用这个。
  • ${env:PATH}：读取系统的环境变量。

4. 环境变量：别再手动 set 了

搞开发的谁还没几个 API Key 或者数据库密码？直接写死在代码里是找死，每次手动 set 是找虐。

方案一：直接写在 launch.json 里（适合简单粗暴）

1
2
3
4
"env": {
    "DEBUG": "true",
    "API_KEY": "sk-xxxxxx"
}

缺点：容易不小心提交到 Git 里，泄露机密。

方案二：使用 .env 文件（强烈推荐）

这是最优雅的做法。

  1. 在项目根目录建一个 .env 文件：
    1
    2
    DATABASE_URL=postgres://localhost:5432/db
    API_KEY=sk-secret-key
  2. 在 launch.json 里引用它：
    1
    "envFile": "${workspaceFolder}/.env"
  3. 记得把 .env 加入 .gitignore！

5. 进阶玩法：用户输入与多环境

场景：我想在运行时选择环境

有时候我想跑开发环境，有时候想跑测试环境，难道要建两个配置？
不用，用 inputs 让 VS Code 弹窗问你。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "configurations": [
        {
            "name": "动态选择环境运行",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "args": ["--env", "${input:selectEnv}"]  // 引用下面的 input
        }
    ],
    "inputs": [
        {
            "id": "selectEnv",
            "type": "pickString",
            "description": "请选择运行环境",
            "options": ["dev", "test", "prod"],
            "default": "dev"
        }
    ]
}

配置好后，按 F5，VS Code 就会弹出一个下拉框让你选。这就很舒服了。

6. 调试技巧：除了 F5 还能干啥

配置好了不会用也是白搭。这里有几个我常用的调试骚操作：

1. 条件断点

循环跑了 1000 次，我只想看第 500 次的情况怎么办？
右键点击红色的断点 -> 编辑断点 -> 输入 i == 500。
程序会乖乖在第 500 次停下来。

2. 日志断点 (Logpoints)

线上问题排查神器。不想暂停程序，只想打印一行日志看看？
右键 -> 添加日志点 -> 输入 当前 i 的值是 {i}。
控制台会打印日志，但程序不会暂停。这比你改代码加 print 再重启快多了。

3. 调试控制台 (Debug Console)

程序暂停时，你可以在底部的“调试控制台”里执行任意 Python 代码。
改变量值、调函数、查数据，随心所欲。
比如：user.is_admin = True，直接强行把用户改成管理员，看看权限逻辑对不对。

7. 避坑指南：那些年我踩过的坑

Q: 为什么 input() 卡住了？

A: 检查你的 console 设置。如果设成了 internalConsole（调试控制台），它是只读的，不支持输入。
解法：改成 "console": "integratedTerminal"。

Q: 为什么断点变灰了，进不去？

A:

  1. 代码和运行的代码不一致（没保存？）。
  2. 你在调试第三方库，但开了 "justMyCode": true"。
  3. 这是一个多进程程序，但没开 "subProcess": true"。

Q: 怎么调试 Docker 里的代码？

A: 这属于 attach 模式的范畴了。需要在 Docker 里启动程序时开启调试端口（如 debugpy），然后在 VS Code 里配置 request: attach 去连接那个端口。

8. Web 框架特供：Django & Flask

Django 和 Flask 用户看过来，这里有你们专属的配置。

Django 完美配置

1
2
3
4
5
6
7
8
9
{
    "name": "Django: Run Server",
    "type": "debugpy",
    "request": "launch",
    "program": "${workspaceFolder}/manage.py",
    "args": ["runserver", "--noreload"], // --noreload 很重要，否则断点可能乱跳
    "django": true,  // 开启 Django 特殊支持（模板调试等）
    "justMyCode": true
}

Flask 完美配置

1
2
3
4
5
6
7
8
9
10
11
12
{
    "name": "Flask: Run",
    "type": "debugpy",
    "request": "launch",
    "module": "flask",
    "env": {
        "FLASK_APP": "app.py",
        "FLASK_ENV": "development"
    },
    "args": ["run", "--no-debugger"], // 关闭 Flask 自带的调试器，用 VS Code 的
    "jinja": true // 开启 Jinja2 模板调试
}

总结

launch.json 就像是给你的代码装了个方向盘。一开始你可能觉得直接跑直线（终端运行）挺快，但一旦路况复杂（需要调试、环境变量、参数），有个方向盘才能让你游刃有余。

别偷懒，花 10 分钟配好它，以后每天都能省下半小时。