====== 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 script ''build'') - 新建 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'' ===== 四、同时跑多个 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 运行配置 ===== - 打开项目 A 的 ''package.json'',''scripts'' 里 ''dev'' 左边有绿色三角,点它 → ''Run 'dev''' 或 ''Debug 'dev''' - WebStorm 会自动建一个 npm 配置:''Package.json'' 指向 A、''Command'' 是 ''dev''、工作目录也是 A - 到 B、C 项目里各重复一次 - 之后在右上角下拉框里切换、点 Run,几个站点互不干扰地各起一个 好处是运行配置记住了各自的工作目录,不用再 ''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" } } * ''-n'' 给每行日志加前缀(web / admin / api),''-c'' 上色,一眼看出是哪个站点在输出 * ''npm --prefix ../web run dev'' 等价于先 ''cd'' 再跑,跨平台不用写 ''cd'' * 等价替代:''npm-run-all --parallel dev:*'' * ''Ctrl+C'' 一次全停,这是它比多标签最省事的地方 ===== 4.6 同时调试多个 dev server ===== 每个站点配一个 ''JavaScript Debug'' 配置(见第三节),URL 填各自的端口: * site-a → ''http://localhost:5173'' * site-b → ''http://localhost:5174'' 只要端口不冲突、sourcemap 正常,这些调试会话可以同时挂着,断点各停各的,互不干扰。 ===== 五、调试技巧 ===== ===== 5.1 断点打在哪儿 ===== * 断点打在 ''.ts'' / ''.tsx'' 源码行上,靠 source map 映射到编译产物 * 断点**空心或灰色**:该行没有可执行代码(注释、空行、''interface''、纯类型声明) * 断点带**感叹号**:源码与运行中的代码版本对不上,通常是产物过期或 sourcemap 没生效 ===== 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 函数断点 | 直接停在方法入口,不用翻到那一行 | 填函数名,可设为只命中一次 | * **临时断点**:按住 ''Alt'' 点行号区域,命中一次后自动消失,比手动删断点清爽 * **''debugger;'' 语句**:等价于断点,改代码时顺手写一行,适合只验证一处 * **Mute Breakpoints**:一键静音所有断点,位置保留,排查完再开 * **条件表达式别夹带副作用**:别在条件里写 ''console.log''、也别改对象,否则会污染正在观察的状态 * **异步代码慎暂停**:Node 一暂停 ''event loop'' 也停,''fetch'' / ''axios'' 的请求可能直接超时,这类位置优先用 Logpoint * **多个调试会话**:Compound 起的一组 dev server,各 session 的断点可以在 ''View Breakpoints'' 里分别启用或静音 ===== 5.3 查看数据的技巧 ===== 三个主面板分工不同: * **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) ---- 参考:[[typescript:第二十一章_调试]] ```mdk height=520 color=#2563eb # 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 = 端口被别的项目占用 ```