企业官网建设流程全解析

• 后端
• 微服务
• 云原生

本指南面向使用 Midway（@midwayjs/koa等 Web 框架）进行开发的工程师，系统讲解如何在 VSCode 与 WebStorm/IDEA 中为 Midway 项目配置断点调试。读完本文，你将掌握 JavaScript Debug Terminal 免配置调试、launch.json精确调试、IDE npm 运行配置调试三种方案，并理解 Midway 启动过程与调试器交互的底层原理，从而在本地开发、单元测试等场景中高效定位问题。

调试前置：先理解npm run dev做了什么

Midway 项目的开发启动命令统一收敛在package.json的scripts中。以仓库内置示例 samples/koa-esm-app/package.json 为例：

{ "scripts": { "dev": "cross-env NODE_ENV=local mwtsc --watch --run @midwayjs/mock/app", "test": "cross-env NODE_ENV=unittest mocha" } }

这条dev命令做了三件事：

1. 通过cross-env把NODE_ENV显式设置为local（对应 Midway 的本地开发环境，参见文档 site/docs/environment.md 对环境的说明）；
2. 通过mwtsc --watch对 TypeScript 源码进行增量编译并监听文件变化，实现热重载；
3. 通过--run @midwayjs/mock/app调用 @midwayjs/mock 提供的应用启动入口，直接在TypeScript 源码上启动应用。

这正是 Midway 调试的关键点：开发模式下应用运行的是src目录下的.ts源码（而非编译后的dist），因此断点可以直接打在.ts源码行上。从源码看，packages/mock/src/creator.ts 中的create方法在启动时显式设置了process.env.MIDWAY_TS_MODE = 'true'，而 packages/bootstrap/src/bootstrap.ts 的getBaseDir()也会依据是否 TypeScript 环境来决定加载src还是dist，从而保证断点命中源码。

应用启动后默认监听7001端口，文档 site/docs/quickstart.md 中通过npm run dev后访问http://127.0.0.1:7001即可看到Hello midwayjs!。如果你想换端口，可以直接修改scripts，例如：

"dev": "cross-env NODE_ENV=local mwtsc --watch --run @midwayjs/mock/app --port 6001"

理解了这些，下面的调试配置才能做到"知其然也知其所以然"。

在 VSCode 中调试：方法一，JavaScript Debug Terminal

VSCode 在终端下拉菜单中内置了一个特殊终端JavaScript Debug Terminal。点击它创建出的终端自带调试能力，无需任何launch.json配置，输入任意命令都会自动进入 Debug 模式。

具体步骤：

1. 在 VSCode 顶部菜单打开终端（Terminal），点击终端面板右侧的下拉箭头；
2. 在列表中选择JavaScript Debug Terminal；
3. 在新终端中输入npm run dev（或npm test等任意命令）；
4. 在源码上打好断点，发起 HTTP 请求（如访问http://127.0.0.1:7001）即可命中断点。

这种方式尤其适合快速验证：不需要关心端口、环境变量等细节，VSCode 会自动把命令产生的进程以及其派生的子进程纳入调试器管理。

在 VSCode 中调试：方法二，配置launch.json

当需要对启动参数做精细控制（如固定端口、指定环境变量、崩溃自动重启）时，推荐使用 VSCode 启动配置文件。

创建启动文件

在 VSCode 中按下Ctrl+Shift+P（macOS 为Cmd+Shift+P）打开命令面板，输入Debug: Open launch.json（或直接点击左侧"运行和调试"面板的"创建 launch.json 文件"），选择Node.js模板，VSCode 会为你的项目创建一个.vscode/launch.json文件。

推荐的 Midway 配置

将下面的完整配置复制进launch.json：

{ // 使用 IntelliSense 了解相关属性。 // 悬停以查看现有属性的描述。 // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387 "version": "0.2.0", "configurations": [{ "name": "Midway Local", "type": "node", "request": "launch", "cwd": "${workspaceRoot}", "runtimeExecutable": "npm", "windows": { "runtimeExecutable": "npm.cmd" }, "runtimeArgs": [ "run", "dev" ], "env": { "NODE_ENV": "local" }, "console": "integratedTerminal", "protocol": "auto", "restart": true, "port": 7001, "autoAttachChildProcesses": true }] }

配置好后，在源码任意位置打上断点，点击"运行和调试"面板中的Midway Local启动即可。下面逐项说明关键参数的作用：

从源码理解端口参数的影响

Midway 应用监听端口的解析逻辑集中在 packages/web-koa/src/framework.ts 的启动过程中：

• 优先读取process.env.MIDWAY_HTTP_PORT，其次使用配置中的listenOptions.port；
• 当端口为0时，框架会自动调用getFreePort()分配一个空闲端口，并将实际端口写回process.env.MIDWAY_HTTP_PORT（可通过框架的getPort()读取）；
• 最终通过this.server.listen(listenOptions)启动 HTTP 服务。

因此，如果你在scripts里通过--port 6001修改了应用端口，建议同步把launch.json中的port改为6001（该值用于 VSCode 调试器自身，避免与应用端口混淆造成冲突）。

结合 mock 工具链理解启动链路

--run @midwayjs/mock/app背后是 packages/mock/src/creator.ts 的完整引导逻辑：create会读取项目package.json判断模块加载类型（esm或commonjs）、自动将baseDir指向src、创建 mock 专用容器并初始化全局应用上下文。也就是说，调试时应用走的正是测试与开发共用的 mock 启动链路，所以你在测试用例中遇到的启动问题（如 site/docs/mock.md 中描述的createApp、mockContext等用法），在调试会话中往往可以复现，便于前后对照定位。

在 WebStorm / IDEA 中调试

JetBrains 系 IDE（WebStorm、IntelliJ IDEA Ultimate）通过Run/Debug Configurations支持对 npm 脚本的断点调试，配置步骤如下。

第一步：新建 npm 运行配置

1. 打开Run（运行）菜单，选择Edit Configurations...（编辑配置）；
2. 点击左上角+，在列表中选择npm；
3. 在右侧package.json一栏选择你的项目根目录下的package.json文件。

第二步：选择要调试的 Scripts

在配置面板中，Scripts下拉框会自动列出你package.json中scripts段配置好的全部命令（dev、test、build等）。选择你希望调试的命令，例如dev或test：

• 调试开发启动流程：选择dev；
• 调试单元测试：选择test（Midway 测试基于 jest，参考 packages/mock/src/creator.ts 中close对测试环境的处理，测试进程同样可被 IDE 调试器接管）。

如需修改开发端口，与前面一致：改scripts中的dev命令，例如加上--port 6001。

第三步：打断点并执行调试

在.ts源码行号处点击打上断点，点击 IDE 工具栏的Debug按钮（虫子图标）启动调试。应用启动后，向http://127.0.0.1:7001发起请求，即可在断点处暂停，查看变量、调用栈并单步执行。

断点调试实战技巧与常见问题

技巧一：在框架启动流程中打断点

如果想观察 Midway 应用从启动到就绪的完整过程，可以在以下位置打断点：

• packages/bootstrap/src/bootstrap.ts 的Bootstrap.run()，其中注册了SIGINT/SIGTERM等信号处理和uncaughtException兜底日志，并打印[midway:bootstrap] current app started；
• packages/web-koa/src/framework.ts 的server.listen回调，可观察端口绑定与MIDWAY_HTTP_PORT环境变量的写入时机；
• 应用自身的 configuration.ts 中onReady生命周期方法，可观察中间件、过滤器注册的实际执行顺序。

技巧二：调试测试用例

调试 jest 用例时，建议在 IDE/VSCode 中选择test脚本而不是dev，并在 packages/mock/src/creator.ts 的create入口处打断点，确认MIDWAY_TS_MODE与baseDir是否符合预期。结合 site/docs/testing.md 的说明，可以顺藤摸瓜排查"用例启动失败"类问题。

常见问题排查

总结

Midway 的调试链路非常清晰：开发模式下应用直接运行 TypeScript 源码，端口默认7001，启动过程由@midwayjs/mock与@midwayjs/bootstrap协作完成。基于这一前提，VSCode 用户既可以用 JavaScript Debug Terminal 零配置起步，也可以用launch.json做精细化控制；WebStorm/IDEA 用户通过 npm 运行配置即可获得同等的断点调试能力。掌握这些方法后，无论是排查业务逻辑、框架生命周期问题，还是调试测试用例，都能做到有的放矢。

• 后端
• 微服务
• 云原生