写launch.json这事儿看起来是个小任务实际上一折腾起来能让人怀疑人生。断点不生效、路径对不上、环境变量传不进去、多进程项目不知道挂哪个……这些坑我基本都踩过一遍。配置这东西很多人复制一份别人的配置改两下就开跑出问题时完全不知道从哪下手。这篇文章我打算从调试器的工作机制讲起把launch.json里最常见的配置项、变量解析、任务编排、踩坑链路都梳理一遍结合Python和Node.js两个高频场景给出能直接用的配置希望能帮你在下次遇到调试问题时不再是CtrlShiftB反复重启项目瞎试而是先打开launch.json冷静看一眼。1. 为什么launch.json经常配了不如不配先搞清楚调试器的两条路径1.1 launch启动模式与attach附加模式的本质区别在VSCode里创建或打开任意一个项目按下CtrlShiftD或者点击左侧调试图标第一次运行调试的时候系统通常会问你要选什么环境。选完之后VSCode会帮你在项目根目录下的.vscode文件夹里生成一个launch.json。这个文件本质上就是一份调试会话的配置文件告诉调试器我要启动哪个程序用什么解释器/运行时带哪些参数在哪个端口等连接等等。但很多人不知道launch.json里的核心概念其实是两个模式launch和attach。launch模式调试器负责把程序启动起来。比如你配置了Python的request: launch调试器就会用指定的python路径去执行你的main.py。此时程序的生命周期由调试器管理程序退出调试就基本结束。attach模式调试器不负责启动程序而是连接到一个已经在运行中的进程。最典型的就是Node.js项目里先用命令行node --inspect把服务跑起来然后让VSCode的调试器attach到那个调试端口上。这在调试Docker容器内的应用、远程服务器上的进程或者调试那些不能由IDE直接拉起的环境时特别有用。为什么要区分这两个模式因为很多人调试不了的第一大原因就是混淆了这两个概念。比如你的代码明明是跑在远程容器里的你却在launch.json里用了launchVSCode自然会在本地去找启动命令找不到就会报无法启动程序或者直接抛出路径错误。从实践经验看本地直接调试首选launch凡是进程已经存在只需要把调试器挂上去的场景都要走attach。判断标准很简单你问自己一句这个进程现在是不是已经跑起来了如果是那就应该用attach。1.2 从零生成launch.json两种入口方式的差异我见过不少人从来不用VSCode的自动生成功能都是手动新建文件结果经常因为格式错误或者缺少必填字段整个调试半天起不来。这里我建议分两种情况第一种情况项目根目录还没有.vscode文件夹。你可以在运行和调试面板里点击创建launch.json文件VSCode会按当前打开的文件类型来推荐调试环境。比如你当前打开的是一个.py文件它就会推荐Python如果打开的是.js文件就会推荐Node.js。这个入口的好处是VSCode会帮你写出一份当前环境下可以跑通的最基础配置包含默认端口、默认路径、默认参数大大降低起步门槛。第二种情况已经存在launch.json但里面只有一段配置。这种情况更适合手动编辑。直接打开.vscode/launch.json在configurations数组里手动追加新的配置对象。要注意VSCode对JSON文件的格式是零容忍的任何尾逗号、注释格式、缩进混乱都可能让配置直接不生效。VSCode的launch.json其实支持JSONC格式就是允许带注释的JSON变体所以你可以写//注释但不能写裸的true或者把注释写在字符串中间。关于入口还有个小技巧如果你装了多个调试扩展比如同时装了Python和Node.js相关扩展在创建launch.json时VSCode会问你选择环境一定要选对。我遇到过有人项目里既有前端Node服务又有后端Python服务结果他在打开JS文件时创建了launch.jsonVSCode默认生成的配置全是Node.js的Python那边自然怎么也跑不起来。这种情况最好拆成多个配置文件后面我会讲到或者手动把所有需要的配置都写进configurations数组里。2. 一份能直接上手的配置Python与Node.js的典型场景拆解2.1 Python项目配置Django/Flask调试的关键参数Python调试在launch.json里最常见的就是调试脚本、调试Django、调试Flask这三种场景。很多人以为只改一下program指向入口文件就够了实际上不太够。先看一个最基础的调试当前文件配置{ version: 0.2.0, configurations: [ { name: Python: 当前文件, type: python, request: launch, program: ${file}, console: integratedTerminal, justMyCode: false } ] }这个配置里program: ${file}表示调试当前打开的文件console: integratedTerminal表示程序输出和交互都在VSCode下方的集成终端里进行这样能正常接收标准输入。justMyCode: false很关键它让调试器也可以进入第三方库的内部代码进行断点调试当你怀疑库里面是不是出问题了的时候没有这个配置就只能干瞪眼。再来看Django项目的典型场景。如果你直接在launch.json里把program指向manage.py然后参数传runserver当然也能跑但调试体验会很差因为Django自带的runserver会自动重启子进程断点经常一刷新就失效。更好的做法是{ name: Python: Django, type: python, request: launch, program: ${workspaceFolder}/manage.py, args: [runserver, 0.0.0.0:8000, --noreload], django: true, justMyCode: false }这里核心的奥秘是--noreload参数和django: true。--noreload关掉了开发服务器的自动重载让调试器能稳定地在一个进程里命中断点django: true让调试器启用Django模板调试支持也就是说你在模板文件里也能打断点看变量这在排查页面渲染问题时相当有用。Flask项目则建议用module: flask或者直接指定入口脚本。如果你的项目用flask run命令启动那么让调试器执行入口文件反而更简单{ name: Python: Flask, type: python, request: launch, module: flask, env: { FLASK_APP: app.py, FLASK_ENV: development, FLASK_DEBUG: 0 }, args: [run, --no-debugger, --no-reload], jinja: true }注意FLASK_DEBUG设置为0是因为调试器本身已经在做断点控制了如果让Flask自己也跑一个debugger进程两个调试器会互相抢反而断点不灵。jinja: true和Django里的django: true是一个性质启用模板调试。一个我在实际项目里反复踩到的坑是program和module是互斥的两个都写了后面的会静默覆盖前面的配置看起来对但实际上完全不是你想启动的那个入口。如果发现程序启动的位置跟你预想的不一样第一个要检查的就是这里。2.2 Node.js项目配置调试入口与环境变量注入Node.js调试和Python调试有一个很大的不同Node.js原生支持调试协议你不需要装什么额外的调试库只要有Node.js运行时VSCode就能直接接上。最简单的Node.js launch配置是这样的{ name: Node.js: 启动入口, type: node, request: launch, program: ${workspaceFolder}/src/index.js, env: { NODE_ENV: development }, skipFiles: [node_internals/**] }skipFiles: [node_internals/**]这个配置建议不要删它可以让调试器跳过Node.js内部模块的代码不然你在调试时一单步就可能跳进Node的底层层层叠叠的源码里极度影响心情。如果你的入口是用ts-node跑的TypeScript项目呢很多人以为必须配置一个单独的编译任务其实也不用那么复杂{ name: Node.js: TS启动, type: node, request: launch, runtimeExecutable: node, runtimeArgs: [--loader, ts-node/esm], program: ${workspaceFolder}/src/index.ts, env: { TS_NODE_TRANSPILE_ONLY: true } }对于用npm run dev启动的项目一个非常省事的思路是用runtimeExecutable: npm配合runtimeArgs来跑。比如{ name: Node.js: npm dev, type: node, request: launch, runtimeExecutable: npm, runtimeArgs: [run, dev], console: integratedTerminal, autoAttachChildProcesses: true }autoAttachChildProcesses: true这行是我强烈建议加的。Node.js项目经常会通过npm脚本再拉起子进程比如Next.js的dev模式下npm脚本会再启动一个独立worker进程来跑实际的服务端代码。如果不开启这个选项你断点打在服务端代码里会发现调试器根本没有连接到那个子进程断点全灰。加上这个配置后调试器会自动附加到所有子进程上省去一大堆手动查pid再attach的麻烦。在Node.js场景里还有一个高频需求是调试时传命令行参数。用args数组传给你的程序比如args: [--port, 3001, --mode, test]注意这些参数是给program指定的那个入口文件用的不是给node运行时用的。要是把运行时参数比如--inspect、--max-old-space-size也写进argsNode会直接报bad option。3. launch.json的变量系统花括号里的魔法与陷阱3.1 常用内置变量的解析规则launch.json里有一堆以${}包裹的变量很多人只会用${workspaceFolder}和${file}剩下的基本靠猜。其实这些变量调试器在启动会话时就会完成替换搞懂它们的含义能节省大量时间。变量含义使用场景${workspaceFolder}当前打开工作区的根目录路径大多数路径的基座${workspaceFolderBasename}当前工作区根目录的文件夹名不含路径动态生成运行日志文件名${file}当前活动文件中被打开的那个文件的绝对路径调试单个文件${fileWorkspaceFolder}当前活动文件所在的工作区根目录当文件可能在子项目里时的路径定位${fileDirname}当前活动文件所在目录的完整路径相对路径更稳定${relativeFile}当前活动文件相对于工作区的相对路径传输到远程调试器时常用${execPath}VSCode可执行文件的路径极少数扩展需要${lineNumber}当前活动文件光标所在行号调试时动态定位行号${env:变量名}读取环境变量注入动态环境配置${command:命令ID}执行VSCode命令并返回结果高级玩法比如用扩展命令动态生成路径我最常用的组合是${workspaceFolder}${pathSeparator}pathSeparator会自动按操作系统替换成/或\用来拼接路径时最稳。很多人直接在Windows上写死\到了Mac或Linux环境就崩这种问题就是因为没用变量而偏要用硬编码分隔符。还有一点要留意${file}这类变量只在当前焦点是某个具体文件时才有意义。如果焦点落在资源管理器里、终端里${file}会被解析为空字符串。配置里如果用了${file}作为程序入口那么你必须把光标点在这个文件里再按F5不然会报无法解析的路径。3.2 环境变量文件envFile的正确用法环境变量注入是launch.json里水最深的一块。它有两种方式直接在env字段里写死键值或者通过envFile指定一个.env文件。两者的区别在于优先级和可维护性。直接写在env里的配置优先级永远高于envFile而且简单的临时调试参数推荐写在env里一眼能看见。但如果项目环境变量特别多尤其是有用户隐私配置密钥、数据库连接串之类全都塞进launch.json会让整个文件变得混乱而且launch.json一般会提交到版本库密钥很容易因此泄露。这种情况下用envFile指向一个被.gitignore忽略的本地.env文件才是最合理的做法。{ name: Python: 带环境变量启动, type: python, request: launch, program: ${workspaceFolder}/run.py, envFile: ${workspaceFolder}/.env.dev, env: { LOG_LEVEL: DEBUG } }这里有个常见的坑默认情况下envFile文件里的变量格式必须是KEYVALUE而且不会覆盖已经存在的系统环境变量。如果你本机的系统环境变量里已经有一个DATABASE_URL而.env.dev里也定义了DATABASE_URL因为系统环境变量优先级更高你的.env配置很可能完全不生效。解决方式是在.env文件里按下划线形式命名或者在系统环境变量里先把这个变量清理掉再或者直接在env里显式指定这份配置因为env的优先级是最高的。另外一个非常容易踩的坑是envFile指定的文件依赖当前工作目录解析。如果VSCode打开的是外层工作区而项目的.env在某个子目录里写相对路径如./config/.env很容易解析到错误的位置。我强烈建议一律从${workspaceFolder}开始写完整路径不要偷懒写相对路径。4. 复合调试与任务编排让调试器先把项目跑起来4.1 preLaunchTask把启动命令前置很多项目在启动调试前需要先做一些准备工作比如前端需要先编译、后端需要先启动某个依赖服务。这时候在launch.json里配置preLaunchTask就能让调试器在启动程序前先自动跑一个定义在tasks.json里的任务。tasks.json和launch.json是配套存在的。在.vscode/tasks.json里你可以定义一个任务比如{ version: 2.0.0, tasks: [ { label: npm: build, type: npm, script: build, group: build, problemMatcher: [] } ] }然后在launch.json里这样引用{ name: Node.js: 编译后启动, type: node, request: launch, program: ${workspaceFolder}/dist/index.js, preLaunchTask: npm: build }这样每次按F5VSCode都会先自动执行npm run build等编译完成后再启动调试。如果编译报错了调试器会直接终止并显示错误信息不会傻乎乎地去启动一个旧的dist文件。有个小细节preLaunchTask的值必须和tasks.json里某个label完全一致包括大小写和空格。因为这个问题我见过好几个同事配置了半天F5之后直接弹Might be a problem with task提示查了半小时才发现是任务标签里多了个空格。还有一个常见需求是先启动依赖服务再开始调试。比如你要调试一个后端接口但项目要求先有一个Redis和MySQL。你可以定义一组任务然后在这组任务里把依赖服务都拉起来。tasks.json支持dependsOn字段比如{ label: start: all deps, dependsOn: [task: redis, task: mysql] }注意dependsOn里的任务标识是任务列表里的label这个字段拼错同样会直接失败。用好这个机制你的F5一键调试体验会好很多新同事拿到项目也不用看文档就能直接调试。4.2 Compounds组合多个调试会话实际业务里经常需要同时启动多个调试会话。典型场景是前端项目调试加上后端项目调试一起跑或者是一个微服务项目里用户主服务和一个异步任务worker需要同时挂上调试器。launch.json顶层有一个compounds数组允许你把多个配置组合成一个复合配置。举例来说{ version: 0.2.0, configurations: [ { name: 前端: node服务, type: node, request: launch, program: ${workspaceFolder}/frontend/server.js }, { name: 后端: python服务, type: python, request: launch, program: ${workspaceFolder}/backend/app.py } ], compounds: [ { name: 前后端联调, configurations: [前端: node服务, 后端: python服务] } ] }在运行和调试面板顶部的下拉列表里选中前后端联调这个复合配置按F5VSCode会同时拉起两个调试会话所有断点都同时生效。调试的时候你可以在调用堆栈面板里手动切换当前正在查看的调试会话这个体验是很多IDE做不到的。使用compounds时有个性能上和稳定性上的注意点复合配置会同时启动所有子配置如果某个子配置有stopAll之类的互相依赖逻辑很可能会造成其中一个会话启动失败。而且内存消耗也是成倍增长项目过大时建议只同时挂必要的会话。遇到复合配置里某个会话就是起不来的情况先把复合配置拆开单独跑一下各子配置定位是哪个会话的问题再决定是补preLaunchTask还是改端口。4.3 调试端口冲突最容易被忽略的干扰源不管是launch模式还是attach模式端口冲突都是一个非常隐蔽又极其常见的坑。Node.js调试默认以9229作为检查端口Python的debugpy默认监听5678。如果你开了两个Node调试会话同时又没有显式给它们指定不同端口后启动的那个就会因为端口被占用而启动失败或者即使启动了调试器也连不到正确的进程上。解决办法是在配置里显式指定端口{ name: Node.js: 主进程调试, type: node, request: launch, program: ${workspaceFolder}/src/index.js, port: 9230 }以及{ name: Node.js: worker调试, type: node, request: launch, program: ${workspaceFolder}/src/worker.js, port: 9231 }调试端口标签port的默认值都是根据调试器内部逻辑生成的两个同类型配置如果不手动改端口会出现第二个配置的调试器连接到了第一个配置的进程上这种诡异现象。判断方法也很简单在那两个会话里分别打上不同日志或者断点看看到底是哪个会话先被触发。如果发现会话之间串了第一时间检查的就是端口配置。5. 实测中高频踩坑的四个问题与完整排查链路5.1 断点不生效先查调试器是否真正附加到进程断点不生效是launch.json问题里最高频的一个。现场通常是这样代码里打了红色断点按F5启动后断点处的圆点不是实心红而是变成了空心程序一路跑到底调试控制台一点反应都没有。遇到这个问题我的排查链路是固定的从外到内一步步查第一步看面板。运行和调试面板最下面有一个调试控制台DEBUG CONSOLE里面会打印调试器的启动日志。如果看到类似Could not connect to debug target或者Debug adapter process has terminated的字样基本可以断定调试器根本没有连上目标进程。这通常是端口问题或者启动路径问题。第二步看进程。在集成终端里手动用命令行启动同一个程序如果命令行启动正常只有调试器启动失败那问题大概率出在launch.json的环境变量或者启动参数上。如果命令行启动同样失败说明你的程序本身启动就有问题跟launch.json无关。第三步看模式。确认你当前是launch还是attach。如果是attach确认要连接的进程是不是真的活着、端口是否匹配、进程启动时是不是带了正确的--inspect或--debug参数。Node.js在启动时没有加--inspect你用attach模式去连接结果必然是超时。第四步看源码映射。如果你的代码是编译过的比如TypeScript项目编译成了JavaScript而你在.ts源文件里打了断点那么必须让调试器知道源文件和编译产物的映射关系。Node.js场景通常在tsconfig.json里设置sourceMap: truePython场景则要确保断点在当前解释器能找到的路径下。给自己提个醒断点按钮与源码内容必须是一一对应的任何编译步骤都可能打断这个对应关系。我遇到过最离谱的一次是同事在一个Python项目里调试断点打在一个被大量调用但路径很深的方法里怎么都不命中。最后发现启动配置里写的是justMyCode: true而这个方法所在的文件恰好被Python解释器识别成了库代码——因为目录名太像第三方包了。改成justMyCode: false之后断点立刻生效。这类问题不看调试日志根本定位不到。5.2 路径不一致sourceMap与远程路径映射路径问题在launch.json里同样是顽固型杀手。尤其当你调试的是Docker容器内进程、SSH远程环境、WSL环境时本地的路径和远程的路径很可能不一致。你在本地源码/Users/me/project/src/index.ts上打的断点对应的远程容器里可能跑的是/app/src/index.js两边路径对不上调试器自然无法把断点落到正确位置。解决思路是配置sourceMap相关的参数。Node.js的配置项长这样{ name: Node.js: 远程容器调试, type: node, request: attach, port: 9229, sourceMaps: true, outFiles: [${workspaceFolder}/dist/**/*.js] }这里的outFiles就是告诉调试器编译产物JavaScript文件在哪些路径下调试器拿到这些信息后才能根据source map文件把断点从源码位置映射到实际执行的JavaScript位置最终让你在源码文件里打的断点生效。对于Python/typescript以外的场景如果IDE和运行时路径不同通常要配置pathMappings格式类似pathMappings: [ { localRoot: ${workspaceFolder}, remoteRoot: /app } ]我一直建议团队在给远程调试写launch.json时把路径相关的配置当成必须显式声明而不是顺手加上。因为少写一个sourceMaps或outFiles表面看配置没报错程序也能启动但断点就是不生效。这种静默失败比直接报错更折磨人排查效率极低。5.3 跨平台跨环境问题注释、分隔符与命令差异launch.json和tasks.json要提交到版本库里这意味着团队不同成员的运行环境可能不同有人Windows有人macOS有人Linux有人前端用npm有人用pnpm。如果配置里任何命令、路径使用了平台特定的写法换台机器就会出问题。我列举几个最常见的不兼容点路径分隔符Windows使用\其他系统使用/。哪怕配置里夹着一条${workspaceFolder}\\node_modules\\.bin\\webpack在macOS上就会直接被解析成一个不存在路径。应该用${pathSeparator}替代或者尽量用/。命令调用方式在Windows上运行node_modules/.bin/webpack需要借助cmd的脚本而macOS/Linux上则直接指向二进制文件。如果你在task里写死命令比如command: ./node_modules/.bin/vue-cli-service serveWindows上会因为找不到该文件而失败。更好的做法是用type: npm、type: shell这些VSCode内置的任务类型让VSCode自己处理平台差异。环境变量赋值语法Windows命令行的环境变量写法是set NODE_ENVproduction node app.js而Unix是NODE_ENVproduction node app.js。这个差异在任何地方出现都极其致命因为不会有友好报错只会以诡异行为呈现。避开这些坑的唯一可靠思路是让VSCode的官方任务类型处理平台差异不要手写出平台相关的命令行。如果你不放心可以在改动配置后找一台不同系统的电脑上跑一遍确认没挂。我每次改配置至少会在Windows和Linux两个环境各验一次。5.4 环境变量注入失败终端继承与envFile优先级环境变量问题比路径问题更隐蔽因为代码往往能正常启动但程序运行起来拿到的值跟你配置的不一样。最常见的两类情况我分开说。第一类是明明在launch.json里配了env但程序里读不到。这种问题十有八九是程序启动时没有通过调试器拉起的环境而是通过了一个自定义shell脚本、docker-compose或者某种task来启动。比如你的配置里preLaunchTask先跑了一个脚本脚本内部又自己设置了环境变量并把某进程启动为后台进程那VSCode调试器对于这个独立进程根本控制不了你的env配置自然也就作用不到它身上。判断方法在程序里打印一下process.env或者os.environ看看实际运行时值到底长什么样再反推是哪一层把它换了。第二类是envFile里写的变量没生效。前面提过系统环境变量优先级高于envFile而env字段优先级高于两者。如果你发现某个变量死活按你的预期走先确认你的环境因素里有没有同名的系统环境变量。一个实践经验是把.env文件分为.env.example、.env.development、.env.test在launch.json里固定引用明确的那个别用一个统一的.env因为团队协作时大家很可能各自改了本地.env最后你调试时用的是谁的值都说不清。6. 把launch.json收进团队仓库前我习惯做的三件事6.1 区分个人调试配置与团队共享配置launch.json最让人头疼的协作问题是它默认会和代码一起提交到版本库。你的本地路径、本地环境变量、数据库连接串、个人使用的调试端口一旦提交所有同事都会看到。这不仅仅是隐私问题更会造成混乱——同事拉下来代码F5一键调试跑起来用的居然是作者本机的路径和密码。我的做法是在团队里推广一套约定launch.json里只放通用的、可复现的配置比如用它启动本地开发服务用它复合联调前后端。凡是跟机器环境强相关的配置比如本机数据库地址、个人令牌、专属调试脚本一律放在被Git忽略的.vscode/launch.local.json里或者不在。VSCode并不直接支持加载第二个launch文件但可以通过扩展比如Launch Multiple相关扩展来实现目录拆分。不过我个人更推荐一个更朴素的办法launch.json只保留基础配置其余个人化参数全部通过envFile引到.env.local而这个.env.local在.gitignore里一并忽略。团队里还能立一个规矩改launch.json必须同步更新一份docs/debugging.md写明这个配置是干什么的、依赖什么前置服务、端口是什么。这个小文档能省下大量为什么我按F5起不来的提问时间。6.2 用命名规范和配置分组让联调一目了然launch.json的configurations数组可以包含很多配置名字取不好运行和调试面板的下拉列表就会长成一大串毫无规律的名字。我见过有人把所有配置都叫PythonNode或者叫调试1调试2这种命名比不写配置文件更灾难。我的命名习惯是两层结构前缀表示服务或模块后缀表示模式。比如Web: server调试 (launch)Web: server调试 (attach)API: worker调试 (launch)API: 测试用例运行这样在运行和调试面板的下拉列表里一眼就能看出我这会儿要跑什么。另外同类型用途的配置尽量放在一个独立的JSON文件里。launch.json其实支持一个字段叫presentation可以给配置分组排序presentation: { group: backend, order: 1 }配置里的group会在调试面板中按组显示工整很多。配合compounds前端、后端、基础设施三组定位非常快。6.3 给launch.json做版本记录这个建议偏工程管理但实际收益很高。launch.json、tasks.json这类文件属于改了死不了人不改又很难受的隐形资产。我建议团队每次在代码评审里专门对.vscode目录的变更做一次审查哪怕只是改了一个端口号。因为这类文件一旦被某个人改了通常影响的是整个团队的调试体验而且问题往往不是在改的时候爆发而是某个同事在另一个分支上拉到新配置后突然起不来。我做过的有效操作是把.vscode/launch.json的关键配置项在README里列成一张表格写明每项的用途和注意事项之后谁要改配置先对照表格看有没有破坏其他人的预期。最后分享一个我个人的习惯每次新拉一个项目第一件事不是急着跑业务代码而是先把launch.json从头到尾看一遍搞清楚这个项目默认从哪个入口调试、依赖哪些环境变量、有没有前置编译任务。这个先看配置文件再动手的习惯帮我避开了大量看着能跑实际哪儿都不对的调试困境。配置文件这个东西平时看着不起眼出了问题它就是唯一的线索来源值得花十分钟好好读懂。
