一次典型的 SAP UI5 应用白屏的问题定位和分析

笔者最近负责维护一个 SAP UI5 应用，组内其他同事最近提交了新的 git commit，merge 到 main 分支后，执行 regression test 发现白屏了：

打开 Chrome 开发者工具，发现错误消息：

failed to load JavaScript resource: sap/m/item.js - sap.ui.ModuleSystem

ui5loader-dbg.js:1199 Uncaught (in promise) ModuleError: failed to load 'sap/m/item.js' from https://sapui5.hana.ondemand.com/resources/sap/m/item.js: script load error

根据错误消息提示，试图加载 sap/m/item.js 这个 module 时报错。

展开 callstack，发现了 XMLTemplateProcessor.js 的身影。显然，SAP UI5 框架在解析 XML 视图时，触发的这个 module 加载动作。

UI5 装载器总是按模块名映射出一个 URL，再去下载对应脚本。

模块名大小写严格敏感，并且各段用斜杠分隔，例如 sap/m/Select、sap/ui/core/Item。

官方文档明确强调：模块名必须用唯一、大小写敏感的名字来寻址。

错误日志里出现了小写路径 sap/m/item.js，这说明代码的某处在声明或推导一个名为 sap/m/item 的模块，而 UI5 会据此生成 .../sap/m/item.js 去加载。当目标文件不存在或大小写不匹配时，就会报 script load error，白屏随之出现。

不过让我觉得奇怪的是，sap.m 库并不存在一个叫 sap/m/Item 的控制。可复核的通用 Item 类型在 sap.ui.core 库，类名是 sap.ui.core.Item（模块名 sap/ui/core/Item）。

我凭直觉判断：代码里极可能把 core:Item 误写成了 m:item（甚至小写 item），或在 sap.ui.define / require 中拼了错误的模块名 sap/m/item。这两种写法都会把装载器引向一个不存在的 sap/m/item.js。

于是我以 item 为关键字进行了全文搜索，发现了线索。

在 HBox 这个 container 控件里，有一个叫 item 的聚合，在 Visual Studio Code 里显示红色。

鼠标放上去之后提示，在 HBox 下没有名叫 item 的聚合，正确的名称应该是 items，这应该是一个 typo.

将 item 置换成 items 之后，这个白屏现象消失。

总结一下，当 SAP UI5 应用加载时遇到白屏现象，不少新手可能会觉得无从入手。本例错误消息给出的 sap/m/item.js 很容易误导人，如果对 sap.m 不熟的开发者，很容易被这个错误消息带偏，花大力气去研究为什么 item.js 加载出错。殊不知 sap.m 下面根本就不存在 item.js 这个 module，而是因为开发者在 XML 视图里定义了错误的聚合名称，才会让 SAP UI5 loader 去加载一个实际并不存在的 module.