使用UI5 Tooling更新SAPUI5版本时遇specVersion不兼容错误

问题背景 #

原有ui5.yaml配置如下：

specVersion: "2.3"
metadata:
  name: itcpc.cms
type: application
framework:
  name: SAPUI5
  version: "1.84.26"
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.tnt
    - name: themelib_sap_fiori_3
server:
  customMiddleware:
    - name: odataProxy
      beforeMiddleware: serveResources

执行yarn ui5 use sapui5@latest将SAPUI5版本更新到1.118.0后，运行ui5 serve出现以下错误：

info normalizer:translators:ui5Framework Using SAPUI5 version: 1.118.0

⚠️  Process Failed With Error

Error Message:
Invalid ui5.yaml configuration for project @openui5/sap.tnt

Unsupported "specVersion"

C:\Users\10119451\.ui5\framework\packages\@openui5\sap.tnt\1.118.0\ui5.yaml:2

1: ---
2: specVersion: "3.0"
   ^
Your UI5 CLI installation might be outdated.
Supported specification versions: "2.3", "2.2", "2.1", "2.0", "1.1", "1.0", "0.1"
error Command failed with exit code 1.

问题原因 #

SAPUI5 1.118.0版本中的sap.tnt库使用了specVersion: 3.0，但本地安装的UI5 CLI版本过低，仅支持最高2.3的规格版本，导致配置解析失败。

解决步骤 #

• 更新UI5 CLI到最新版本
  执行以下命令（根据包管理器选择）：

  # 使用yarn全局更新
  yarn global add @ui5/cli@latest
  # 或使用npm全局更新
  npm install -g @ui5/cli@latest
  

  新版本的UI5 CLI（v3.x及以上）已经支持specVersion 3.0，可以兼容新的库配置。

• 验证CLI版本
  运行命令确认更新成功：

  ui5 --version
  

  确保版本为v3.x及以上。

• 重新启动服务
  再次执行ui5 serve，服务即可正常启动，不再出现specVersion不兼容错误。

备选方案（不推荐） #

如果暂时无法升级CLI，可以将SAPUI5版本降级到仍使用specVersion 2.x的版本（比如1.117.x及以下），修改ui5.yaml中的framework.version后重新运行服务。但长期来看，升级CLI是更合理的选择，能支持后续SAPUI5版本的新特性。

内容的提问来源于stack exchange，提问作者Adam Harkus