**这是本文档旧的修订版!**
WebStorm 调试 TypeScript
一句话原则:断点永远打在 .ts 源码上,真正执行的是编译后的 JS,靠 source map 把两边对上。
零、前置准备
- 装好 Node.js(
node -v、npm -v能输出版本) - 项目里装依赖:
npm i -D typescript ts-node # ESM 项目更省事的选择 npm i -D tsx
tsconfig.json必须打开sourceMap:
{
"compilerOptions": {
"target": "ES2022",
"module": "commonjs",
"rootDir": "src",
"outDir": "dist",
"sourceMap": true,
"strict": true
},
"include": ["src"]
}
sourceMap 没开,后面所有步骤都会变成“断点打了但停不下来”。
一、方式 A:直接调试 .ts 文件(推荐)
让 ts-node / tsx 在运行时就地编译,不用手动 build。
- 右上角运行配置下拉框 →
Edit Configurations…→+→Node.js - 关键字段:
| 字段 | 填写内容 |
|---|---|
| Name | debug index |
| Node interpreter | 默认的 node |
| JavaScript file | src/index.ts(直接选 .ts 文件) |
| Application parameters | 传给脚本的参数,如 –env dev |
| Working directory | 项目根目录 |
| Node parameters | CommonJS 项目:–require ts-node/register;ESM 项目:–import tsx(Node 20+)或 –loader ts-node/esm |
| Environment variables | 按需补充 |
- 点
Debug按钮(绿色小虫子,Windows 快捷键Shift+F9,macOS 用Ctrl+D) - 在
src/index.ts的行号左侧点一下,打上红点断点
更快的路径:编辑器里右键 .ts 文件 → Debug 'index.ts',WebStorm 会自动生成上面的配置(首次会提示装 ts-node)。
二、方式 B:先编译再调试 JS(最稳)
适合 ts-node 在 ESM 下反复报错、或者你本来就依赖构建产物的情况。
- 先编译:
npx tsc(或 npm scriptbuild) - 新建 Node.js 运行配置,
JavaScript file选dist/index.js - 断点仍然打在
.ts源码里 —— sourceMap 开着就能停住 - 改代码后要重新编译:开一个常驻终端跑
npx tsc -w,或在配置的Before launch里加一个 tsc 任务
如果单步跳到了 dist/xxx.js 里,说明 sourceMap 没生效或者产物过期,回第零步检查。
三、方式 C:前端项目(Vite / webpack + 浏览器)
浏览器里跑的 TS(React、Vue 等)用 JavaScript Debug 配置:
- 先在 Terminal 起开发服务器:
npm run dev(假设是 http://localhost:5173) Edit Configurations…→+→JavaScript Debug- URL 填
http://localhost:5173 - 点 Debug,WebStorm 拉起浏览器,
.ts/.tsx里的断点直接生效 - Vite 开发模式自带 sourcemap;生产构建排查要开
build.sourcemap = true
四、调试技巧
- 条件断点:右键已打的断点 →
Condition填i === 5,只在条件成立时停 - Logpoint(日志断点):右键断点 → 取消
Suspend,勾上Evaluate and log,写处理到 ${id}—— 只打印不暂停,适合循环里看值 - Variables 面板:看当前作用域的局部变量与闭包
- Watches:把关键表达式固定进来,单步时实时刷新
- Evaluate Expression(
Alt+F8):调试中执行任意表达式,也能临时改状态 - Console 面板:同样可以跑代码、看输出
- 行内值提示:单步后行尾会直接显示变量当前值
Mute Breakpoints:一键静音所有断点,位置保留
调试控制键(Windows / 括号内为 macOS):
| 操作 | 快捷键 |
|---|---|
| Run | Shift+F10(Ctrl+R) |
| Debug | Shift+F9(Ctrl+D) |
| Step Over 单步跳过 | F8 |
| Step Into 进入函数 | F7 |
| Step Out 跳出函数 | Shift+F8 |
| Resume 继续运行 | F9 |
| Evaluate Expression | Alt+F8 |
五、常见坑
- 断点是灰色/空心的:该行没有可执行代码,或文件没被编译进去。检查
include、rootDir,确认 ts-node 真的启用了 - 断点打在 .ts 却停在 .js:
sourceMap没开,或产物没重新编译 - 路径别名 @/xxx 报错:ts-node 要配
tsconfig-paths:
npm i -D tsconfig-paths # 然后在 Node parameters 里追加 -r tsconfig-paths/register
“type”: “module”下 ts-node 各种报错:别硬刚,换tsx,Node parameters 写–import tsx- 找不到配置文件、相对路径错乱:把运行配置里的
Working directory设为项目根目录 - 改了代码没生效:方式 B 是编译型的,记得重新 build 或开
tsc -w
参考:第二十一章_调试
# WebStorm 调试 TypeScript ## 前置准备 ### 安装 Node.js ### tsconfig 开启 sourceMap ### 装 ts-node 或 tsx ## 方式 A 直跑 .ts ### Node.js 运行配置 ### JavaScript file 选 .ts ### Node parameters 加 --require ts-node/register ## 方式 B 编译后调 JS ### tsc 产出 dist ### 断点仍打在 .ts ### 配合 tsc -w ## 方式 C 浏览器调试 ### JavaScript Debug 配置 ### URL 填 dev server 地址 ### Vite 开发模式自带 sourcemap ## 调试技巧 - 条件断点 Condition - Logpoint 只打印不暂停 - Variables 与 Watches - Evaluate Expression - Mute Breakpoints ## 常见坑 - 断点灰色 = 该行无可执行代码 - 停在 .js = sourceMap 未生效 - 别名 @ 报错 = 加 tsconfig-paths - ESM 报错 = 换 tsx - 路径错乱 = 改 Working directory