webstorm

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
  • 条件断点:右键已打的断点 → 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

该主题尚不存在

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

  • webstorm.1791903402.txt.gz
  • 最后更改: 2026/10/13 22:56
  • 由 张叶安