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 没开,后面所有步骤都会变成“断点打了但停不下来”。

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

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

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

  • 先编译:npx tsc(或 npm script build)
  • 新建 Node.js 运行配置,JavaScript file 选 dist/index.js
  • 断点仍然打在 .ts 源码里 —— sourceMap 开着就能停住
  • 改代码后要重新编译:开一个常驻终端跑 npx tsc -w,或在配置的 Before launch 里加一个 tsc 任务

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

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

  • 先在 Terminal 起开发服务器:npm run dev(假设是 http://localhost:5173)
  • Edit Configurations… → + → JavaScript Debug
  • 点 Debug,WebStorm 拉起浏览器,.ts / .tsx 里的断点直接生效
  • Vite 开发模式自带 sourcemap;生产构建排查要开 build.sourcemap = true

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

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 保证跨平台)

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

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

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

  • 打开项目 A 的 package.json,scripts 里 dev 左边有绿色三角,点它 → Run 'dev' 或 Debug 'dev'
  • WebStorm 会自动建一个 npm 配置:Package.json 指向 A、Command 是 dev、工作目录也是 A
  • 到 B、C 项目里各重复一次
  • 之后在右上角下拉框里切换、点 Run,几个站点互不干扰地各起一个

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

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

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

项目路径固定、只想省事就选这个。在任意一个总目录里建 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"
  }
}
  • -n 给每行日志加前缀(web / admin / api),-c 上色,一眼看出是哪个站点在输出
  • npm –prefix ../web run dev 等价于先 cd 再跑,跨平台不用写 cd
  • 等价替代:npm-run-all –parallel dev:*
  • Ctrl+C 一次全停,这是它比多标签最省事的地方

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

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

  • 断点打在 .ts / .tsx 源码行上,靠 source map 映射到编译产物
  • 断点空心或灰色:该行没有可执行代码(注释、空行、interface、纯类型声明)
  • 断点带感叹号:源码与运行中的代码版本对不上,通常是产物过期或 sourcemap 没生效

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 函数断点 直接停在方法入口,不用翻到那一行 填函数名,可设为只命中一次
  • 临时断点:按住 Alt 点行号区域,命中一次后自动消失,比手动删断点清爽
  • debugger; 语句:等价于断点,改代码时顺手写一行,适合只验证一处
  • Mute Breakpoints:一键静音所有断点,位置保留,排查完再开
  • 条件表达式别夹带副作用:别在条件里写 console.log、也别改对象,否则会污染正在观察的状态
  • 异步代码慎暂停:Node 一暂停 event loop 也停,fetch / axios 的请求可能直接超时,这类位置优先用 Logpoint
  • 多个调试会话:Compound 起的一组 dev server,各 session 的断点可以在 View Breakpoints 里分别启用或静音

三个主面板分工不同:

  • Variables:当前帧的 Local / Closure / Global。双击值可直接改,改完立即影响后面的逻辑
  • Watches:把关键表达式钉住,单步时自动刷新,例如 users.filter(u ⇒ u.done).length
  • Frames 调用栈:点上层任意一帧,Variables / Watches 会切到那一帧的上下文 —— 定位“坏数据是哪个调用方传进来的”基本靠它

看对象时注意两点:

  • 对象 id:{name: 'a'} #231 里的 #231 是引用标识。两个变量显示同一个 id 说明是同一个对象,排查“改了 A 为什么 B 跟着变”一眼可见
  • Mark Object:右键变量标记颜色,同一对象在多处出现会同色高亮,适合追踪一个实例在整条链路上的流转

大数据与异步栈:

  • 长数组 / Map / Set 默认折叠且有渲染上限,Settings → Debugger → Data Views 可调默认展开层级与数组上限,Load more 按需加载
  • 右键 Copy Value(Ctrl+C)能把对象按 JSON 形态复制出来,方便贴到别处比对
  • TS 类型编译后会被擦除,Variables 里看到的是运行时值;判断 null / undefined / NaN 直接用 Evaluate 测
  • Node 12+ 默认提供 async stack trace,Frames 面板能看到 await 之前的调用链;栈“断”在 Promise 里时,检查 Settings → Debugger 里的 async stack traces 是否开启

调试控制键(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
  • EADDRINUSE: address already in use:端口被另一个项目的 dev server 占了。先按 4.1 给每个项目固定不同端口;想知道是谁占的,用 lsof -i :5173(macOS/Linux)或 netstat -ano | findstr :5173(Windows)

参考:第二十一章_调试

# 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 = 端口被别的项目占用

该主题尚不存在

您访问的页面并不存在。如果允许,您可以使用创建该页面按钮来创建它。

  • webstorm.txt
  • 最后更改: 2026/10/14 09:58
  • 由 张叶安