目录

WebStorm 调试 TypeScript

一句话原则:断点永远打在 .ts 源码上,真正执行的是编译后的 JS,靠 source map 把两边对上。

零、前置准备

npm i -D typescript ts-node
# ESM 项目更省事的选择
npm i -D tsx
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "rootDir": "src",
    "outDir": "dist",
    "sourceMap": true,
    "strict": true
  },
  "include": ["src"]
}

sourceMap 没开,后面所有步骤都会变成“断点打了但停不下来”。

一、方式 A:直接调试 .ts 文件(推荐)

让 ts-node / tsx 在运行时就地编译,不用手动 build。

字段 填写内容
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 按需补充
  1. 点 Debug 按钮(绿色小虫子,Windows 快捷键 Shift+F9,macOS 用 Ctrl+D)
  2. 在 src/index.ts 的行号左侧点一下,打上红点断点

更快的路径:编辑器里右键 .ts 文件 → Debug 'index.ts',WebStorm 会自动生成上面的配置(首次会提示装 ts-node)。

二、方式 B:先编译再调试 JS(最稳)

适合 ts-node 在 ESM 下反复报错、或者你本来就依赖构建产物的情况。

如果单步跳到了 dist/xxx.js 里,说明 sourceMap 没生效或者产物过期,回第零步检查。

三、方式 C:前端项目(Vite / webpack + 浏览器)

浏览器里跑的 TS(React、Vue 等)用 JavaScript Debug 配置:

四、同时跑多个 npm run dev

手上好几个项目,每个都要常驻一个 dev server 时,按下面由简到繁选一种。

4.1 先给每个项目固定端口

Vite / Next 发现端口被占会自动换一个端口,结果你调试的 URL 和实际端口对不上。所以第一步是把端口钉死:

项目 固定端口的方式
Vite vite.config.ts 里 server.port: 5174,或 npm run dev – –port 5174
Next.js next dev -p 3001
Vue CLI npm run serve – –port 8081
CRA 环境变量 PORT=8081(Windows 下用 cross-env 保证跨平台)

4.2 方案一:多开 Terminal 标签

最简单,适合临时跑两三个项目。底部 Terminal 窗口标签栏点 + 新建标签,一个标签盯一个项目:

# 标签 1
cd ~/code/site-a && npm run dev
 
# 标签 2
cd ~/code/site-b && npm run dev -- --port 5174

缺点是终端一关就得重新敲,标签开多了也容易看错目录 —— 项目固定的话往下走。

4.3 方案二:每个项目一个 npm 运行配置

好处是运行配置记住了各自的工作目录,不用再 cd;配一次一直能用。

注意别把不同项目的 ''.env'' 或端口串在一起。

4.4 方案三:Compound 一键启动全部

Edit Configurations… → + → Compound,把上面几个配置都勾进去,之后点一次 Run/Debug 就全部起来。想要并发分组、自定义启动顺序,可以再装第三方插件 Multirun。

4.5 方案四:一个终端一条命令全跑

项目路径固定、只想省事就选这个。在任意一个总目录里建 package.json,用 concurrently:

npm i -D concurrently
{
  "scripts": {
    "dev": "concurrently -n web,admin,api -c blue,magenta,green \"npm:dev:web\" \"npm:dev:admin\" \"npm:dev:api\"",
    "dev:web": "npm --prefix ../web run dev",
    "dev:admin": "npm --prefix ../admin run dev -- --port 5174",
    "dev:api": "npm --prefix ../api run dev"
  }
}

4.6 同时调试多个 dev server

每个站点配一个 JavaScript Debug 配置(见第三节),URL 填各自的端口:

只要端口不冲突、sourcemap 正常,这些调试会话可以同时挂着,断点各停各的,互不干扰。

五、调试技巧

5.1 断点打在哪儿

5.2 比行断点更好用的几种断点

Ctrl+Shift+F8(macOS Cmd+Shift+F8)打开 View Breakpoints,点 + 添加:

类型 适用场景 关键设置
条件断点 Condition 循环到第 N 次才停、只在某个用户或 ID 上停 填 JS 表达式,如 i === 5、user.id === 42
Logpoint 日志断点 高频循环 / 回调,不想反复按 F9 取消 Suspend,勾 Evaluate and log,写 处理到 ${id}
Exception 异常断点 排查“这个错是谁抛的” Catch class 填 TypeError,再用 Condition 收窄
Function 函数断点 直接停在方法入口,不用翻到那一行 填函数名,可设为只命中一次

5.3 查看数据的技巧

三个主面板分工不同:

看对象时注意两点:

大数据与异步栈:

调试控制键(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

六、常见坑

npm i -D tsconfig-paths
# 然后在 Node parameters 里追加
-r tsconfig-paths/register

参考:第二十一章_调试

# 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
## 同时跑多个 dev server
### 先给各项目固定端口
### 方案一 多开 Terminal 标签
### 方案二 每项目一个 npm 运行配置
### 方案三 Compound 一键启动全部
### 方案四 concurrently 一条命令全跑
### 每站一个 JavaScript Debug 配置
## 调试技巧
### 断点打在哪儿
- 断点打在 .ts 源码,靠 source map
- 灰色或空心 = 该行无可执行代码
- 感叹号 = 产物过期或 sourcemap 失效
### 断点类型 View Breakpoints
- 条件断点 Condition
- Logpoint 只打印不暂停
- Exception 断点 Catch class
- Function 断点 停在方法入口
### 打断点的手感
- 临时断点 Alt + 点行号
- debugger; 语句等价断点
- Mute Breakpoints 一键静音
- 条件里别夹带副作用
- 异步代码慎暂停,优先 Logpoint
- 多会话断点可分别静音
### 看数据的主面板
- Variables 可双击改值
- Watches 钉住表达式
- Frames 调用栈切帧看调用方
### 快速看值
- 行内值提示
- 悬停 tooltip 可加 Watch
- Evaluate Expression Alt+F8
- Console 当 REPL
### 看对象的门道
- 对象 id 判断是否同一引用
- Mark Object 同色高亮
- Copy Value 复制成 JSON
- 类型会被擦除,只看运行时值
### 大数据与异步栈
- 调整数组与展开层级上限
- Node async stack trace
## 常见坑
- 断点灰色 = 该行无可执行代码
- 停在 .js = sourceMap 未生效
- 别名 @ 报错 = 加 tsconfig-paths
- ESM 报错 = 换 tsx
- 路径错乱 = 改 Working directory
- EADDRINUSE = 端口被别的项目占用