简介这份资源是一份完整的VSCode中调试TypeScript的配置与演示包适合正在学习TypeScript或希望提升调试效率的前端、Node开发者参考。压缩包共10个文件包含2个TypeScript源码示例、5个json配置文件如launch.json、tsconfig.json、package.json以及readme说明文档等包体仅5KB结构精炼便于直接对照学习。目前已有1975人浏览/学习。资源围绕本地Node应用与Chrome前端调试两条主线提供源码入口、sourceMap配置、调试启动脚本与配套说明读者可基于示例快速理解断点设置、变量监视、调用堆栈等核心操作并迁移到自己的项目中减少排查问题的时间成本。1. 在 VSCode 中调试 TypeScript断点打不上症结多半在源码映射做 vscode-typescript-debugging 这套配置之前我一直有个错觉VSCode 世界第一装个插件、按个 F5TypeScript 的断点就该老老实实命中。后来真上手才发现断点打在 .ts 文件里毫无反应、命中的全是编译后的 JS、变量面板一片 any才是最普遍的开局。原因不在编辑器而在调试器不认 TypeScript它执行和调试的是 JavaScript一切都要靠 sourcemap 把两者对齐。这个标题要解决的就是编辑、编译、调试三者之间的映射关系让你不用退回 console.log 过日子。适合刚把项目切成 TS 的开发者也适合那些配置过一把但总在断点上翻车、想一次理顺的人。2. 先让 TypeScript 能在 Node 里跑tsconfig 与运行时选型的 4 个决定点2.1 tsconfig.json 里影响调试的三个开关sourceMap、outDir、sourceRootTypeScript 源码不能直接被 Node 执行调试器加载的始终是编译产物。你按 F5 时VSCode 先看 program 指向的入口文件把它交给 Node 跑起来再用.js.map文件把运行时的调用栈映射回.ts源码。这一串里任何一个环节缺失断点就会集体罢工。tsconfig.json 里最关键的开关是sourceMap它决定编译时是否生成.js.map文件。没有这个文件调试器看到的只有 JS你在 TS 里按断点永远显示空心圆。第二个是outDir编译产物落到哪个目录launch.json 里的 program 和 outFiles 就得跟着这个目录写写岔了就找不到目标。第三个是sourceRoot一般情况下不需要手动设置但当你把项目放进 monorepo 或容器里源码路径和本地不一致时sourceRoot或sourceMapPathOverrides才是救场工具。{ compilerOptions: { target: ES2022, module: CommonJS, outDir: ./dist, rootDir: ./src, sourceMap: true, inlineSources: true, strict: true }, include: [src] }这段是编译后调试方案的基础配置。module用 CommonJS 是因为它对 Node 调试链路的兼容性最稳ESM 项目也能调但断点命中率受 Node 版本影响Windows 上更容易出路径大小写的问题。inlineSources会把 TS 源码写进.js.map文件调试器断点时能直接显示原始 TS 内容代价是产物体积略大。我的习惯是调试用的 tsconfig 开着它发布构建用的 tsconfig 关掉它。2.2 运行时选型编译后运行、ts-node 直跑、Node 原生 strip-types决定怎么调试之前得先决定项目怎么跑。常见做法是三条路选错一条后面的 launch.json 就全拧着来。第一条路最传统tsc编译到 distNode 直接跑 dist 里的 JS。这条路的调试配置最简单且和线上行为完全一致线上也是跑编译产物。缺点是每次改代码都要等编译大项目全量构建够喝一杯咖啡的。第二条路用ts-node或tsx直跑.ts源文件省掉编译步骤适合脚本、接口联调、单元测试这类快速验证场景。调试器这时要加载的是src/index.ts配置完全不同于编译后调式program字段直接指向.ts再用runtimeArgs挂一个转译器注册器。第三条路是 Node 较新版本的内置 strip-types 能力靠参数直接把 TypeScript 的类型注解剥掉再执行但 enum、namespace 这类特性会直接报错调试态可用线上不建议依赖属于“能跑但别认真”的形态。方案调试配置复杂度与线上行为一致性启动速度tsc 编译后运行低高慢要等构建ts-node / tsx 直跑中中快免编译Node 原生 strip-types中低快但特性受限不少项目还叠加了 webpack、vite 这类前端构建链那又是另一套调试方式后面单独展开。选型时记住一个原则如果项目里已经有tsc -w在终端挂着优先选编译后调试连 preLaunchTask 都可以省掉改完代码等一两秒热编译再按 F5 重挂调试器即可这是我最常用的一条路径。3. 写对 launch.jsonNode.js 调试的核心字段与最小可运行配置3.1 最简 launch.jsonprogram、preLaunchTask、outFiles 怎么填VSCode 的调试能力是内置的 JavaScript Debugger 提供的不需要额外安装第三方调试插件。你要做的只是告诉它跑哪个文件、怎么编译、编译产物在哪。一份最简配置长这样{ version: 0.2.0, configurations: [ { name: Launch TS (compiled), type: node, request: launch, program: ${workspaceFolder}/dist/index.js, preLaunchTask: tsc: build - tsconfig.json, outFiles: [${workspaceFolder}/dist/**/*.js], sourceMaps: true, console: integratedTerminal, skipFiles: [node_internals/**] } ] }program指向的是编译后的dist/index.js特别容易有人写成src/index.ts一旦写成 TS 源码编译后调试方案里 Node 会直接报错因为 Node 根本不认识.ts后缀。preLaunchTask告诉调试器启动前先执行哪个任务它对应 tasks.json 里某个 task 的label两个文件里的名字必须一模一样。outFiles是调试器找编译产物的搜索范围如果你把产物输出到了 build 目录这里不跟着改断点照样灰。sourceMaps默认就是 true但显式写出来排查问题时你少一个怀疑方向。skipFiles用来跳过 Node 内部模块否则单步调试时一步就扎进require的实现里爬不出来。配套还要一份 tasks.jsonpreLaunchTask 才好使{ version: 2.0.0, tasks: [ { label: tsc: build - tsconfig.json, type: typescript, tsconfig: tsconfig.json, problemMatcher: [$tsc], group: build } ] }这段 task 用的是 VSCode 内置的 TypeScript 构建能力不用手写command: tsc。problemMatcher会把 tsc 输出的错误信息解析进“问题”面板比干巴巴的终端输出直观很多。如果你在 VSCode 里执行过“Tasks: Run Build Task”会看到同名的 tsc 任务这就是 preLaunchTask 能直接引用它的原因。3.2 调试 npm scripts在 package.json 里定义调试入口而不是硬改 launch.json项目跑起来往往不是一条裸的node dist/index.js而是nest start --watch、webpack-dev-server、vite dev、nodemon --exec node dist/index.js这类被包进 package.json 的脚本。这时候把 launch.json 写成program指向 JS 入口就绕过了脚本里挂载的环境变量和命令行参数调试出来的状态和真实运行不一致白费功夫。常见做法是让 launch.json 直接驱动 npm 脚本{ name: Launch via npm, type: node, request: launch, runtimeExecutable: npm, runtimeArgs: [run, dev], console: integratedTerminal, timeout: 30000 }runtimeExecutable换成 npm 之后调试器通过 npm 把 dev 脚本拉起然后附加到实际产生的 Node 进程上。timeout是等待进程出现的超时时间脚本启动前有数据库连接、配置加载这类耗时操作时默认值不够用按分钟级调是常态。这套方案里不需要写 program 和 outFiles断点能不能命中取决于脚本最终跑出来的进程是否带有 sourcemap 信息以及它的工作目录和 tsconfig 的 rootDir 是否一致。如果 dev 脚本内部还套了一层 nodemon就多一个坑nodemon 会在文件变化时杀掉旧进程再起新进程调试器的附加连接会随之断裂。更稳的做法是在 nodemon 配置里让进程主动暴露调试端口再让 launch.json 以 attach 模式连接这个组合放到避坑章节细说。4. 三类场景的分治编译后调试、ts-node 直跑与浏览器断点4.1 编译后调试最稳的路径watch 模式下怎么省时间编译后调试是团队项目里最值得先跑通的方案因为它和线上跑的代码是同一份不会出现本地能调、线上报错对不上的情况。流程分两步先在终端起tsc -w做增量编译改完代码后 dist 目录自动更新再按 F5 用第 3 章的 launch.json 把调试器挂上去。很多人一上来就把preLaunchTask写死成编译任务结果大项目每次 F5 都全量编译启动慢到怀疑人生。我一般把这个字段删掉让终端里的tsc -w常驻调试器只负责挂载启动时间从几十秒压到一两秒。这个取舍一定值得编译交给 watch调试器只做它该做的事。断点打在src/*.ts里调试器通过.js.map映射到源码。如果某个文件的断点突然变灰先检查 dist 目录下是否真的生成了对应的.js.map文件没有就是 tsconfig 改动导致 sourceMap 没生成或者文件根本没进编译范围。另外一个隐蔽问题出现在 monorepo 里如果 package 之间的依赖是通过 workspace 符号链接进来的调试器按相对路径找不到源码这时要在 launch.json 里显式指定cwd或者用sourceMapPathOverrides把.map文件里的路径强制映射到本地 workspacesourceMapPathOverrides: { webpack:///./src/*: ${workspaceFolder}/src/*, webpack:///src/*: ${workspaceFolder}/src/* }这段的左右两个路径分别代表编译工具生成的源码引用格式和本地磁盘上的真实路径凡是遇到 monorepo、pnpm workspace、yarn PnP 这类开了符号链接的环境这个字段都值得先看一眼。4.2 ts-node 与 tsx 直跑省掉编译配置上的关键一行不需要产物、追求快速反馈的时候用 ts-node 直跑最舒服。它绕过了“改代码 → 编译 → 重启”的循环但 launch.json 的写法要跟着换一整套{ name: Launch via ts-node, type: node, request: launch, program: ${workspaceFolder}/src/index.ts, runtimeArgs: [-r, ts-node/register], console: integratedTerminal, cwd: ${workspaceFolder} }注意这里的program是.ts文件本身Node 启动时靠-r ts-node/register在引导阶段注册了一个转译器让require能直接加载 TS 模块。断点能否命中依赖 ts-node 内部生成的 sourcemap所以 tsconfig 里的sourceMap依然要开着这一点不因为“免编译”而免除。如果你用的是tsx写法更短runtimeArgs: [--import, tsx]或者更省心一点直接不写 program让tsx作为运行入口{ runtimeExecutable: tsx, args: [src/index.ts] }tsx 基于 esbuild转译速度比 ts-node 快一个量级缺点是它不做类型检查类型错误得靠tsc --noEmit另外守门。对调试本身来说esbuild 生成的 sourcemap 和 TS 源码的对齐效果通常足够好。Node 新版自带的--experimental-strip-types也能直跑 TS但遇到 enum 直接报错调试器对这种模式的 sourcemap 支持也不算完整我的建议是尝鲜可以正经项目别往里搭调试环境。4.3 前端调试浏览器调试器与 webpack 的 source-map 联调前端项目的调试入口不在 Node而在浏览器。VSCode 的 launch.json 这时换type: chrome调试器通过 DevTools 协议连上浏览器断点直接打在.ts源码里。{ name: Debug Frontend, type: chrome, request: launch, url: http://localhost:5173, webRoot: ${workspaceFolder}/src }url指向本地开发服务器地址端口要和 vite、webpack-dev-server 的配置一致写错了调试器会打开一个空白页面愣住。webRoot告诉调试器去哪里找源码文件vite 项目一般指向项目根目录老式 webpack 项目要看 loader 配置。前端这层能不能断上七成取决于构建工具的 sourcemap 配置。webpack 里devtool: source-map或inline-source-map二选一module.exports { mode: development, devtool: inline-source-map }inline-source-map把 map 内容塞进 bundle 的 data URL 里浏览器 DevTools 和 VSCode 调试器都能解析缺点是 bundle 体积明显变大但这本来就是 development 模式不用心疼。vite 默认在 dev 模式开 sourcemap不需要额外配置。一旦你发现断点能命中但源码内容显示不对先查 dev 模式的 sourcemap 是不是被谁关了。前端调试最让新人挠头的是“能停但停错位置”比如断点打在UserList组件上命中的却像是另一个同名文件。这种往往是 webpack 的模块 ID 和源码路径映射串位直接清掉浏览器缓存和 dist 缓存再不行就换 Chrome 的“清缓存并硬性重新加载”。5. 断点不生效与玄学报错常见问题排查清单5.1 断点是灰色空心圆outFiles 没覆盖或 sourcemap 路径错位现象断点显示为一个空心圆鼠标悬停提示 “Bound breakpoint not found”编译产物明明存在就是不停。原因第一个嫌疑是 launch.json 里的outFiles没有覆盖编译产物的实际目录比如产物在 build 但 outFiles 写的是 dist。第二个嫌疑是.js.map文件里的sources字段指向的源码路径在 workspace 里找不到这在 monorepo 里尤其常见。解决先打开 dist 下对应文件的.js.map看sources字段里的路径长什么样。如果是webpack:///./src/index.ts就在 launch.json 配sourceMapPathOverrides映射回${workspaceFolder}/src。如果根本没有.js.map文件回 tsconfig 确认sourceMap: true。5.2 断点命中但变量全是 any 或 undefined现象断点停住了但变量面板里要么是any要么值是undefined根本没法看数据。原因.js.map文件里没有内联源码内容或者修改源码后没有重新编译调试器拿到的映射还是旧的。另一个经常被忽略的因素是文件被多个断点共享VSCode 在某次会话里加载错了映射版本。解决在 tsconfig 里把inlineSources: true打开让 map 文件自带源码快照调试器即使找不到本地源码也能显示变量名。改完源码后记得确认编译产物时间戳是和源码同步的tsc -w挂在后台时偶尔会漏编译边缘文件直接重启一下 watcher 最省事。5.3 Windows 下调试控制台中文乱码现象断点命中了但调试控制台里 tsc 的报错信息全是一类的乱码根本读不出错误内容。原因VSCode 调试控制台按 UTF-8 解码输出而 Windows 下的 cmd 默认代码页是 GBK两边对不上中文就全变火星文。解决把 launch.json 里的console从internalConsole改成integratedTerminal让进程直接向 VSCode 的终端输出终端按子进程的代码页解析乱码问题自然消失。如果乱码出在 tasks.json 里的构建任务可以在 command 前面加一段代码页切换{ label: tsc: build - tsconfig.json, type: shell, command: cmd /c chcp 65001 tsc -p tsconfig.json, problemMatcher: [$tsc] }cmd /c chcp 65001在启动 tsc 之前把控制台切到 UTF-8跟在终端手敲chcp 65001是一个效果只是不用每台机器都手动设。5.4 断点该停不停或停在了不该停的下一行现象设置完条件断点后明明满足条件却不命中或者普通断点在异步回调里第二次执行时直接跳过。原因条件表达式写得太宽松。x 1和x 1在调试条件下是两回事前者遇到字符串类型的1也会为 true闭包循环变量for (let i...)如果断点打到的是索引行号映射有概率偏差。还有一类是 logpoint 误设成了表达式变成了永不触发的副作用。解决条件断点一律用严格比较x 1不满足就换typeof x number x 1。异步回调连续执行时第一次命中断点第二次不命中排查方向先看映射再考虑把断点挪到回调函数体的第一行而不是函数声明的那一行。5.5 F5 弹窗提示找不到 preLaunchTask现象按下 F5VSCode 弹了一个错误提示内容大致是找不到配置里引用的构建任务。原因tasks.json 里 task 的label被改过和 launch.json 里的preLaunchTask字符串不一致或者根目录根本没有 .vscode/tasks.json 这个文件。解决用快捷键 CtrlShiftP 执行 “Tasks: Run Build Task”看任务列表里实际出现的 label 是什么然后让 launch.json 的preLaunchTask和它完全一致注意区分大小写。如果两个文件都是对的把 VSCode 窗口重新加载一次任务注册表有时候也会有不刷新的情况这属于少见的玄学问题但确实会遇到。6. 把调试配置变成团队共用资产一份能传家的 launch.json6.1 用变量和 envFile 代替机器相关的绝对路径调试配置踩过一次环境迁移的坑之后我养成的习惯是 launch.json、tasks.json 一律提交进 Git让新成员克隆完仓库就能按 F5 开调。前提是里面不能出现任何机器相关的东西路径统一用${workspaceFolder}环境变量单独放一份.env.debug通过envFile字段加载{ type: node, request: launch, name: Launch API, envFile: ${workspaceFolder}/.env.debug, program: ${workspaceFolder}/dist/server.js }.env.debug放本地联调用的数据库地址、临时密钥并提交到.gitignore仓库里只放.env.debug.example模板既保证新同事能开箱即跑又不会把真实环境变量带进仓库。6.2 用 compound 一键启动前后端全栈项目最常用的调试组合是“后端 API 前端页面”两个配置一起起。前面配置好了两个 configuration再用 compound 把他们绑成一个入口{ version: 0.2.0, configurations: [ { name: Launch API, type: node, request: launch }, { name: Debug Frontend, type: chrome, request: launch } ], compounds: [ { name: Server Client, configurations: [Launch API, Debug Frontend] } ] }选中 “Server Client” 再按 F5两个调试会话同时挂起后端断点前后端请求数据前端断点看渲染链路两边一起停。代码里设置断点互不干扰中途想关哪边就点对应会话的停止按钮。做调试配置这些年我反复踩的坑总结下来就一句话遇到断点不生效先看调试控制台实际加载的路径再开.js.map看 sources最后才动配置文件。先把事实查清楚再拿配置去碰运气基本一次就能定位。这套方案按前面的步骤搭完你会在日常开发里慢慢习惯有断点可用的状态而不是回到 console.log 时代凑合着过希望帮到你。本文还有配套的精品资源点击获取 VSCode调试TypeScript从入门到排坑：sourcemap与launch.json配置实战
简介这份资源是一份完整的VSCode中调试TypeScript的配置与演示包适合正在学习TypeScript或希望提升调试效率的前端、Node开发者参考。压缩包共10个文件包含2个TypeScript源码示例、5个json配置文件如launch.json、tsconfig.json、package.json以及readme说明文档等包体仅5KB结构精炼便于直接对照学习。目前已有1975人浏览/学习。资源围绕本地Node应用与Chrome前端调试两条主线提供源码入口、sourceMap配置、调试启动脚本与配套说明读者可基于示例快速理解断点设置、变量监视、调用堆栈等核心操作并迁移到自己的项目中减少排查问题的时间成本。1. 在 VSCode 中调试 TypeScript断点打不上症结多半在源码映射做 vscode-typescript-debugging 这套配置之前我一直有个错觉VSCode 世界第一装个插件、按个 F5TypeScript 的断点就该老老实实命中。后来真上手才发现断点打在 .ts 文件里毫无反应、命中的全是编译后的 JS、变量面板一片 any才是最普遍的开局。原因不在编辑器而在调试器不认 TypeScript它执行和调试的是 JavaScript一切都要靠 sourcemap 把两者对齐。这个标题要解决的就是编辑、编译、调试三者之间的映射关系让你不用退回 console.log 过日子。适合刚把项目切成 TS 的开发者也适合那些配置过一把但总在断点上翻车、想一次理顺的人。2. 先让 TypeScript 能在 Node 里跑tsconfig 与运行时选型的 4 个决定点2.1 tsconfig.json 里影响调试的三个开关sourceMap、outDir、sourceRootTypeScript 源码不能直接被 Node 执行调试器加载的始终是编译产物。你按 F5 时VSCode 先看 program 指向的入口文件把它交给 Node 跑起来再用.js.map文件把运行时的调用栈映射回.ts源码。这一串里任何一个环节缺失断点就会集体罢工。tsconfig.json 里最关键的开关是sourceMap它决定编译时是否生成.js.map文件。没有这个文件调试器看到的只有 JS你在 TS 里按断点永远显示空心圆。第二个是outDir编译产物落到哪个目录launch.json 里的 program 和 outFiles 就得跟着这个目录写写岔了就找不到目标。第三个是sourceRoot一般情况下不需要手动设置但当你把项目放进 monorepo 或容器里源码路径和本地不一致时sourceRoot或sourceMapPathOverrides才是救场工具。{ compilerOptions: { target: ES2022, module: CommonJS, outDir: ./dist, rootDir: ./src, sourceMap: true, inlineSources: true, strict: true }, include: [src] }这段是编译后调试方案的基础配置。module用 CommonJS 是因为它对 Node 调试链路的兼容性最稳ESM 项目也能调但断点命中率受 Node 版本影响Windows 上更容易出路径大小写的问题。inlineSources会把 TS 源码写进.js.map文件调试器断点时能直接显示原始 TS 内容代价是产物体积略大。我的习惯是调试用的 tsconfig 开着它发布构建用的 tsconfig 关掉它。2.2 运行时选型编译后运行、ts-node 直跑、Node 原生 strip-types决定怎么调试之前得先决定项目怎么跑。常见做法是三条路选错一条后面的 launch.json 就全拧着来。第一条路最传统tsc编译到 distNode 直接跑 dist 里的 JS。这条路的调试配置最简单且和线上行为完全一致线上也是跑编译产物。缺点是每次改代码都要等编译大项目全量构建够喝一杯咖啡的。第二条路用ts-node或tsx直跑.ts源文件省掉编译步骤适合脚本、接口联调、单元测试这类快速验证场景。调试器这时要加载的是src/index.ts配置完全不同于编译后调式program字段直接指向.ts再用runtimeArgs挂一个转译器注册器。第三条路是 Node 较新版本的内置 strip-types 能力靠参数直接把 TypeScript 的类型注解剥掉再执行但 enum、namespace 这类特性会直接报错调试态可用线上不建议依赖属于“能跑但别认真”的形态。方案调试配置复杂度与线上行为一致性启动速度tsc 编译后运行低高慢要等构建ts-node / tsx 直跑中中快免编译Node 原生 strip-types中低快但特性受限不少项目还叠加了 webpack、vite 这类前端构建链那又是另一套调试方式后面单独展开。选型时记住一个原则如果项目里已经有tsc -w在终端挂着优先选编译后调试连 preLaunchTask 都可以省掉改完代码等一两秒热编译再按 F5 重挂调试器即可这是我最常用的一条路径。3. 写对 launch.jsonNode.js 调试的核心字段与最小可运行配置3.1 最简 launch.jsonprogram、preLaunchTask、outFiles 怎么填VSCode 的调试能力是内置的 JavaScript Debugger 提供的不需要额外安装第三方调试插件。你要做的只是告诉它跑哪个文件、怎么编译、编译产物在哪。一份最简配置长这样{ version: 0.2.0, configurations: [ { name: Launch TS (compiled), type: node, request: launch, program: ${workspaceFolder}/dist/index.js, preLaunchTask: tsc: build - tsconfig.json, outFiles: [${workspaceFolder}/dist/**/*.js], sourceMaps: true, console: integratedTerminal, skipFiles: [node_internals/**] } ] }program指向的是编译后的dist/index.js特别容易有人写成src/index.ts一旦写成 TS 源码编译后调试方案里 Node 会直接报错因为 Node 根本不认识.ts后缀。preLaunchTask告诉调试器启动前先执行哪个任务它对应 tasks.json 里某个 task 的label两个文件里的名字必须一模一样。outFiles是调试器找编译产物的搜索范围如果你把产物输出到了 build 目录这里不跟着改断点照样灰。sourceMaps默认就是 true但显式写出来排查问题时你少一个怀疑方向。skipFiles用来跳过 Node 内部模块否则单步调试时一步就扎进require的实现里爬不出来。配套还要一份 tasks.jsonpreLaunchTask 才好使{ version: 2.0.0, tasks: [ { label: tsc: build - tsconfig.json, type: typescript, tsconfig: tsconfig.json, problemMatcher: [$tsc], group: build } ] }这段 task 用的是 VSCode 内置的 TypeScript 构建能力不用手写command: tsc。problemMatcher会把 tsc 输出的错误信息解析进“问题”面板比干巴巴的终端输出直观很多。如果你在 VSCode 里执行过“Tasks: Run Build Task”会看到同名的 tsc 任务这就是 preLaunchTask 能直接引用它的原因。3.2 调试 npm scripts在 package.json 里定义调试入口而不是硬改 launch.json项目跑起来往往不是一条裸的node dist/index.js而是nest start --watch、webpack-dev-server、vite dev、nodemon --exec node dist/index.js这类被包进 package.json 的脚本。这时候把 launch.json 写成program指向 JS 入口就绕过了脚本里挂载的环境变量和命令行参数调试出来的状态和真实运行不一致白费功夫。常见做法是让 launch.json 直接驱动 npm 脚本{ name: Launch via npm, type: node, request: launch, runtimeExecutable: npm, runtimeArgs: [run, dev], console: integratedTerminal, timeout: 30000 }runtimeExecutable换成 npm 之后调试器通过 npm 把 dev 脚本拉起然后附加到实际产生的 Node 进程上。timeout是等待进程出现的超时时间脚本启动前有数据库连接、配置加载这类耗时操作时默认值不够用按分钟级调是常态。这套方案里不需要写 program 和 outFiles断点能不能命中取决于脚本最终跑出来的进程是否带有 sourcemap 信息以及它的工作目录和 tsconfig 的 rootDir 是否一致。如果 dev 脚本内部还套了一层 nodemon就多一个坑nodemon 会在文件变化时杀掉旧进程再起新进程调试器的附加连接会随之断裂。更稳的做法是在 nodemon 配置里让进程主动暴露调试端口再让 launch.json 以 attach 模式连接这个组合放到避坑章节细说。4. 三类场景的分治编译后调试、ts-node 直跑与浏览器断点4.1 编译后调试最稳的路径watch 模式下怎么省时间编译后调试是团队项目里最值得先跑通的方案因为它和线上跑的代码是同一份不会出现本地能调、线上报错对不上的情况。流程分两步先在终端起tsc -w做增量编译改完代码后 dist 目录自动更新再按 F5 用第 3 章的 launch.json 把调试器挂上去。很多人一上来就把preLaunchTask写死成编译任务结果大项目每次 F5 都全量编译启动慢到怀疑人生。我一般把这个字段删掉让终端里的tsc -w常驻调试器只负责挂载启动时间从几十秒压到一两秒。这个取舍一定值得编译交给 watch调试器只做它该做的事。断点打在src/*.ts里调试器通过.js.map映射到源码。如果某个文件的断点突然变灰先检查 dist 目录下是否真的生成了对应的.js.map文件没有就是 tsconfig 改动导致 sourceMap 没生成或者文件根本没进编译范围。另外一个隐蔽问题出现在 monorepo 里如果 package 之间的依赖是通过 workspace 符号链接进来的调试器按相对路径找不到源码这时要在 launch.json 里显式指定cwd或者用sourceMapPathOverrides把.map文件里的路径强制映射到本地 workspacesourceMapPathOverrides: { webpack:///./src/*: ${workspaceFolder}/src/*, webpack:///src/*: ${workspaceFolder}/src/* }这段的左右两个路径分别代表编译工具生成的源码引用格式和本地磁盘上的真实路径凡是遇到 monorepo、pnpm workspace、yarn PnP 这类开了符号链接的环境这个字段都值得先看一眼。4.2 ts-node 与 tsx 直跑省掉编译配置上的关键一行不需要产物、追求快速反馈的时候用 ts-node 直跑最舒服。它绕过了“改代码 → 编译 → 重启”的循环但 launch.json 的写法要跟着换一整套{ name: Launch via ts-node, type: node, request: launch, program: ${workspaceFolder}/src/index.ts, runtimeArgs: [-r, ts-node/register], console: integratedTerminal, cwd: ${workspaceFolder} }注意这里的program是.ts文件本身Node 启动时靠-r ts-node/register在引导阶段注册了一个转译器让require能直接加载 TS 模块。断点能否命中依赖 ts-node 内部生成的 sourcemap所以 tsconfig 里的sourceMap依然要开着这一点不因为“免编译”而免除。如果你用的是tsx写法更短runtimeArgs: [--import, tsx]或者更省心一点直接不写 program让tsx作为运行入口{ runtimeExecutable: tsx, args: [src/index.ts] }tsx 基于 esbuild转译速度比 ts-node 快一个量级缺点是它不做类型检查类型错误得靠tsc --noEmit另外守门。对调试本身来说esbuild 生成的 sourcemap 和 TS 源码的对齐效果通常足够好。Node 新版自带的--experimental-strip-types也能直跑 TS但遇到 enum 直接报错调试器对这种模式的 sourcemap 支持也不算完整我的建议是尝鲜可以正经项目别往里搭调试环境。4.3 前端调试浏览器调试器与 webpack 的 source-map 联调前端项目的调试入口不在 Node而在浏览器。VSCode 的 launch.json 这时换type: chrome调试器通过 DevTools 协议连上浏览器断点直接打在.ts源码里。{ name: Debug Frontend, type: chrome, request: launch, url: http://localhost:5173, webRoot: ${workspaceFolder}/src }url指向本地开发服务器地址端口要和 vite、webpack-dev-server 的配置一致写错了调试器会打开一个空白页面愣住。webRoot告诉调试器去哪里找源码文件vite 项目一般指向项目根目录老式 webpack 项目要看 loader 配置。前端这层能不能断上七成取决于构建工具的 sourcemap 配置。webpack 里devtool: source-map或inline-source-map二选一module.exports { mode: development, devtool: inline-source-map }inline-source-map把 map 内容塞进 bundle 的 data URL 里浏览器 DevTools 和 VSCode 调试器都能解析缺点是 bundle 体积明显变大但这本来就是 development 模式不用心疼。vite 默认在 dev 模式开 sourcemap不需要额外配置。一旦你发现断点能命中但源码内容显示不对先查 dev 模式的 sourcemap 是不是被谁关了。前端调试最让新人挠头的是“能停但停错位置”比如断点打在UserList组件上命中的却像是另一个同名文件。这种往往是 webpack 的模块 ID 和源码路径映射串位直接清掉浏览器缓存和 dist 缓存再不行就换 Chrome 的“清缓存并硬性重新加载”。5. 断点不生效与玄学报错常见问题排查清单5.1 断点是灰色空心圆outFiles 没覆盖或 sourcemap 路径错位现象断点显示为一个空心圆鼠标悬停提示 “Bound breakpoint not found”编译产物明明存在就是不停。原因第一个嫌疑是 launch.json 里的outFiles没有覆盖编译产物的实际目录比如产物在 build 但 outFiles 写的是 dist。第二个嫌疑是.js.map文件里的sources字段指向的源码路径在 workspace 里找不到这在 monorepo 里尤其常见。解决先打开 dist 下对应文件的.js.map看sources字段里的路径长什么样。如果是webpack:///./src/index.ts就在 launch.json 配sourceMapPathOverrides映射回${workspaceFolder}/src。如果根本没有.js.map文件回 tsconfig 确认sourceMap: true。5.2 断点命中但变量全是 any 或 undefined现象断点停住了但变量面板里要么是any要么值是undefined根本没法看数据。原因.js.map文件里没有内联源码内容或者修改源码后没有重新编译调试器拿到的映射还是旧的。另一个经常被忽略的因素是文件被多个断点共享VSCode 在某次会话里加载错了映射版本。解决在 tsconfig 里把inlineSources: true打开让 map 文件自带源码快照调试器即使找不到本地源码也能显示变量名。改完源码后记得确认编译产物时间戳是和源码同步的tsc -w挂在后台时偶尔会漏编译边缘文件直接重启一下 watcher 最省事。5.3 Windows 下调试控制台中文乱码现象断点命中了但调试控制台里 tsc 的报错信息全是一类的乱码根本读不出错误内容。原因VSCode 调试控制台按 UTF-8 解码输出而 Windows 下的 cmd 默认代码页是 GBK两边对不上中文就全变火星文。解决把 launch.json 里的console从internalConsole改成integratedTerminal让进程直接向 VSCode 的终端输出终端按子进程的代码页解析乱码问题自然消失。如果乱码出在 tasks.json 里的构建任务可以在 command 前面加一段代码页切换{ label: tsc: build - tsconfig.json, type: shell, command: cmd /c chcp 65001 tsc -p tsconfig.json, problemMatcher: [$tsc] }cmd /c chcp 65001在启动 tsc 之前把控制台切到 UTF-8跟在终端手敲chcp 65001是一个效果只是不用每台机器都手动设。5.4 断点该停不停或停在了不该停的下一行现象设置完条件断点后明明满足条件却不命中或者普通断点在异步回调里第二次执行时直接跳过。原因条件表达式写得太宽松。x 1和x 1在调试条件下是两回事前者遇到字符串类型的1也会为 true闭包循环变量for (let i...)如果断点打到的是索引行号映射有概率偏差。还有一类是 logpoint 误设成了表达式变成了永不触发的副作用。解决条件断点一律用严格比较x 1不满足就换typeof x number x 1。异步回调连续执行时第一次命中断点第二次不命中排查方向先看映射再考虑把断点挪到回调函数体的第一行而不是函数声明的那一行。5.5 F5 弹窗提示找不到 preLaunchTask现象按下 F5VSCode 弹了一个错误提示内容大致是找不到配置里引用的构建任务。原因tasks.json 里 task 的label被改过和 launch.json 里的preLaunchTask字符串不一致或者根目录根本没有 .vscode/tasks.json 这个文件。解决用快捷键 CtrlShiftP 执行 “Tasks: Run Build Task”看任务列表里实际出现的 label 是什么然后让 launch.json 的preLaunchTask和它完全一致注意区分大小写。如果两个文件都是对的把 VSCode 窗口重新加载一次任务注册表有时候也会有不刷新的情况这属于少见的玄学问题但确实会遇到。6. 把调试配置变成团队共用资产一份能传家的 launch.json6.1 用变量和 envFile 代替机器相关的绝对路径调试配置踩过一次环境迁移的坑之后我养成的习惯是 launch.json、tasks.json 一律提交进 Git让新成员克隆完仓库就能按 F5 开调。前提是里面不能出现任何机器相关的东西路径统一用${workspaceFolder}环境变量单独放一份.env.debug通过envFile字段加载{ type: node, request: launch, name: Launch API, envFile: ${workspaceFolder}/.env.debug, program: ${workspaceFolder}/dist/server.js }.env.debug放本地联调用的数据库地址、临时密钥并提交到.gitignore仓库里只放.env.debug.example模板既保证新同事能开箱即跑又不会把真实环境变量带进仓库。6.2 用 compound 一键启动前后端全栈项目最常用的调试组合是“后端 API 前端页面”两个配置一起起。前面配置好了两个 configuration再用 compound 把他们绑成一个入口{ version: 0.2.0, configurations: [ { name: Launch API, type: node, request: launch }, { name: Debug Frontend, type: chrome, request: launch } ], compounds: [ { name: Server Client, configurations: [Launch API, Debug Frontend] } ] }选中 “Server Client” 再按 F5两个调试会话同时挂起后端断点前后端请求数据前端断点看渲染链路两边一起停。代码里设置断点互不干扰中途想关哪边就点对应会话的停止按钮。做调试配置这些年我反复踩的坑总结下来就一句话遇到断点不生效先看调试控制台实际加载的路径再开.js.map看 sources最后才动配置文件。先把事实查清楚再拿配置去碰运气基本一次就能定位。这套方案按前面的步骤搭完你会在日常开发里慢慢习惯有断点可用的状态而不是回到 console.log 时代凑合着过希望帮到你。本文还有配套的精品资源点击获取