企业官网建设流程全解析

• 后端
• 微服务
• 云原生

导读

Midway 是面向全栈 / 前后端一体化场景的 Node.js 框架（仓库中同时维护了@midwayjs/bootstrap与 Hooks 全栈方案），本地调试能力的优劣直接影响开发效率。本文围绕 hooks/debug.md 与 docs/debugger.md 两份官方调试文档，系统讲解在 VSCode、WebStorm/IDEA 等主流编辑器/IDE 中调试 Midway 应用的两种核心手段：JavaScript Debug Terminal与npm Scripts 一键 Debug，并补充 launch.json 手工配置、断点命中原理与启动入口分析，帮助读者把「改代码 → 重启 → 看日志」的低效循环，替换为「断点 → 单步 → 查变量」的精准定位流程。

调试的前提：理解 Midway 应用的启动入口

无论使用哪种编辑器，调试的本质都是「以调试模式运行应用进程，再把断点挂到源码上」。因此在动手前，先看清 Midway 应用是如何被启动的。

以仓库中的全栈示例 samples/functional-api-hybrid/package.json 为例，其scripts如下：

{ "scripts": { "build": "tsc -p tsconfig.json", "start": "node dist/bootstrap.js", "test": "cross-env NODE_ENV=unittest mocha" } }

也就是说，npm start实际执行的是node dist/bootstrap.js——先由tsc将 TypeScript 编译到dist，再启动编译产物中的入口文件。而dist/bootstrap.js内部调用的是 packages/bootstrap/src/bootstrap.ts 中导出的Bootstrap：

static async run() { // 注册 SIGINT / SIGQUIT / SIGTERM 等信号处理 process.once('SIGINT', this.onSignal.bind(this, 'SIGINT')); // ... this.runningPromise = this.getStarter() .run() .then(() => { this.logger.info('[midway:bootstrap] current app started'); global['MIDWAY_BOOTSTRAP_APP_READY'] = true; return this.getApplicationContext(); }) .catch(err => { this.logger.error(err); process.exit(1); }); return this.runningPromise; }

从源码可以看到，Bootstrap.run()内部通过BootstrapStarter.init()完成应用上下文初始化（读取package.json的type字段决定 ESM/CommonJS 加载方式、初始化全局容器、启动主框架），并在应用就绪后打印[midway:bootstrap] current app started。这行日志可以当作调试时判断「应用是否真正启动完成」的锚点。

需要留意的是：调试的是 TypeScript 源码还是编译产物，取决于你的启动脚本。若脚本是node dist/bootstrap.js，断点应打在dist下；若希望直接在src里的.ts源码上打断点，则需要让调试器能够处理 TypeScript——这也是下文两种编辑器方案各自要解决的核心问题（VSCode 的自动附加 / 调试器对 ts 的处理）。

方案一：在 VSCode 中调试

方法 A：使用 JavaScript Debug Terminal（零配置）

这是官方文档推荐的最快捷方式，全程不需要编写任何launch.json配置文件：

1. 打开 VSCode，点击顶部菜单Run → Open Configurations，或在活动栏切换到「运行和调试」视图（Ctrl/Cmd + Shift + D）；
2. 在终端面板的下拉菜单中，选择JavaScript Debug Terminal，创建出一个自带调试能力的终端；
3. 在该终端中直接运行任意命令，例如npm start（也可以是你项目scripts中配置的npm run dev等）；
4. VSCode 会自动以调试模式启动该进程，接下来只需在源码中打上断点，请求进来时即可命中。

这套机制的原理是：JavaScript Debug Terminal 中的进程会被 VSCode 内置的 Node 调试器自动附加（Auto Attach），所有在终端里启动的 Node 进程都会继承调试能力，因此「输入命令 → 自动进入调试模式」是一条链路完成的，不需要手动选择进程。

方法 B：使用 Debug Scripts 按钮（可视化选择）

另一种方式同样无需配置文件：

1. 打开项目根目录的package.json；
2. 将鼠标悬停在scripts区域上方，会出现一个Debug按钮；
3. 点击该按钮，VSCode 会弹出当前package.json中定义的所有scripts命令（如start、build、test）；
4. 选择start（或你想要的任意命令），即会以调试模式启动该脚本，之后正常打断点即可。

这种方式与 JavaScript Debug Terminal 殊途同归：都是在调试器托管下执行 npm scripts，适合「鼠标点选、避免手敲命令」的场景，对刚接触调试器的开发者尤其友好。

方法 C：手工编写 launch.json（可复现、可共享）

如果希望把调试配置固化为团队共享的.vscode/launch.json（例如 CI 场景下排除干扰、明确指定端口和参数），可以参考仓库文档 docs/debugger.md 中给出的配置模板：

{ "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 }] }

对这份配置的逐项说明：

配置完成后，在源码行号左侧点击打上断点，再按F5启动调试即可命中。官方文档中的完整操作截图可以继续阅读 docs/debugger.md（其中还包含断点命中后的调试界面演示）。

方案二：在 JetBrains（WebStorm / IDEA）中调试

JetBrains 系 IDE 对 npm scripts 有一等公民的支持，操作路径与 VSCode 的 Debug Scripts 类似：

1. 打开项目的package.json，编辑区顶部会出现各scripts命令对应的行内快捷按钮；
2. 找到scripts中你希望执行的命令（例如start、dev、test），点击其左侧的Debug按钮（绿色小虫子图标）；
3. IDE 会自动创建一个临时的「npm 运行配置」，并直接以调试模式启动该脚本；
4. 在代码中打好断点，发起请求触发对应逻辑，即可进入断点单步调试。

如果你更习惯显式的配置管理，也可以在Run → Edit Configurations中手工新建一个npm类型的运行配置：选择对应的package.json文件，再从 Scripts 下拉框中选择你要执行的命令，勾选 Debug 模式后运行。这种方式与点击行内 Debug 按钮效果完全一致，只是把配置显式保存了下来，便于跨机器复用。

JetBrains 方案的天然优势在于：IDE 对 TypeScript 有内建支持，当你的启动脚本经由ts-node、tsx或编译产物运行时，IDE 通常能正确把断点映射回src下的.ts源码，无需额外配置 source-map 解析。

调试实践中的几个实用要点

基于仓库现状与源码，补充几个容易被忽略、但直接影响调试体验的细节：

• 区分调试入口与工作目录：在 packages/bootstrap/src/bootstrap.ts 中，BootstrapStarter.init()默认以process.cwd()作为appDir，并从package.json的type字段推断moduleLoadType（esm或commonjs）。因此在 IDE 中配置调试时，务必保证运行配置的工作目录（cwd）指向项目根目录，否则会出现「找不到配置 / 加载了错误的包」之类的诡异问题。
• 判断应用是否就绪：Bootstrap.run()成功后会输出[midway:bootstrap] current app started，并把全局标记MIDWAY_BOOTSTRAP_APP_READY置为true。调试时如果迟迟没有命中第一个断点，先确认终端里是否出现了这行日志——它代表框架容器、主框架都已初始化完毕，此时再发请求必然能走到业务代码。
• 环境变量与端口：Midway 会按NODE_ENV加载不同环境的配置（local对应本地开发）。调试时建议显式指定NODE_ENV=local（如 launch.json 模板中的env段），并确认监听的端口与调试端口不冲突。
• 进程信号的优雅关闭：从Bootstrap.run()的源码可见，它注册了SIGINT/SIGQUIT/SIGTERM信号处理，收到信号后会执行stop()并打印close done, exiting with code:0。调试中按Ctrl + C结束应用是安全的，属于受控退出。

小结

针对 Midway 应用的本地调试，本文覆盖了三类常用操作：

• VSCode：零配置的 JavaScript Debug Terminal、点选式的 Debug Scripts 按钮，以及可固化共享的.vscode/launch.json（详见 docs/debugger.md）；
• JetBrains（WebStorm/IDEA）：在package.json的scripts上直接点击 Debug 按钮，或显式创建 npm 运行配置；
• 底层认知：结合 packages/bootstrap/src/bootstrap.ts 的启动流程与示例项目 samples/functional-api-hybrid/package.json 的 scripts，理解「调试进程 → 断点命中」的完整链路。

三种方式本质都是「让调试器托管 Node 进程」，区别只在于配置方式与适用场景：临时调试用 JavaScript Debug Terminal，习惯鼠标操作用 Debug Scripts 按钮，团队协作或需要固定参数（端口、环境变量）时则用 launch.json。掌握其中任意一种，即可告别日志打点式的排障，进入断点级排查的调试模式。

• 后端
• 微服务
• 云原生