sapui5-cli

用途

本技能为使用 UI5 CLI（UI5 Tooling）提供全面指导。UI5 CLI 是开发和构建、部署 SAPUI5 与 OpenUI5 应用及库的官方命令行界面。适用于初始化新 UI5 项目、为已有项目启用 CLI 支持、配置 ui5.yaml、构建项目、运行本地开发服务器、扩展构建流程、管理工作区以及排查错误和版本迁移等场景。

环境要求

当前 CLI 版本：4.0.55（2026-05-31 经 npm 验证）
Node.js：v20.11.0+ 或 v22.0.0+（不支持 v21）
npm：v8.0.0+

主要能力

初始化新 UI5 项目或为已有项目启用 CLI 支持
为 application、library、theme-library、module 配置 ui5.yaml
构建 UI5 项目，支持优化、打包和压缩
运行支持 HTTP/2、SSL 和 CSP 的本地开发服务器
通过自定义任务或服务器中间件扩展构建流程
使用 ui5-workspace.yaml 管理 monorepo/工作区配置
排查常见 UI5 CLI 错误与构建问题
在 CLI 版本间迁移（v1 → v2 → v3 → v4）
优化构建性能并分析依赖

使用方式

新项目快速开始：

# 1. 安装 UI5 CLI（二选一）
npm install --global @ui5/cli          # 全局安装
npm install --save-dev @ui5/cli        # 项目级安装

# 2. 初始化项目（若为新项目）
npm init --yes                          # 初始化 npm
ui5 init                                # 创建 ui5.yaml

# 3. 选择框架变体
ui5 use openui5@latest                  # 用于 OpenUI5
ui5 use sapui5@latest                   # 用于 SAPUI5

# 4. 添加框架库
ui5 add sap.ui.core sap.m sap.ui.table themelib_sap_fiori_3

# 5. 开始开发
ui5 serve                               # 启动开发服务器
ui5 serve --open index.html            # 启动并打开浏览器

# 6. 生产构建
ui5 build --all                         # 构建并包含依赖
ui5 build --clean-dest                  # 构建前清理目标目录

已有项目启用 CLI：

ui5 init
ui5 use openui5@latest                  # 或 sapui5@latest
ui5 tree                                # 查看依赖树
ui5 serve                               # 测试开发服务器

核心命令包括：项目初始化（ui5 init、ui5 use、ui5 add、ui5 remove）、开发（ui5 serve、ui5 tree）、构建（ui5 build preload/self-contained/jsdoc，支持 --all、--include-dependency、--exclude-dependency、--dest、--clean-dest、--create-build-manifest、--experimental-css-variables）、配置（ui5 config set/get/list）以及工具命令（ui5 versions、ui5 --help、ui5 --version）。

项目类型

UI5 CLI 支持四种项目类型：

Application：标准 UI5 应用，含 webapp 目录；虚拟路径映射 webapp/ → /；存在 Component.js 时生成 Component-preload.js。
Library：可复用组件库；虚拟路径映射 src/ → /resources、test/ → /test-resources；需要命名空间目录结构。
Theme Library：为库提供主题资源；虚拟映射与标准库相同；资源按命名空间组织。
Module：第三方资源，路径映射灵活；资源原样复制；支持自定义虚拟到物理路径映射。

配置结构

ui5.yaml 基本结构包含 specVersion（必需）、type（必需）、metadata.name（必需）、framework（name/version/libraries）、resources.configuration.paths、builder.resources.excludes、server.settings 等字段。规范版本方面，4.0 为当前主版本（需 Node.js v20.11.0+），3.0-3.2 兼容 CLI v3.0.0+，2.0-2.6 兼容 CLI v2.0.0+，0.1-1.1 为旧版（会尝试自动迁移）。新项目应始终使用最新 specVersion。框架最低版本：OpenUI5 1.52.5，SAPUI5 1.76.0。

适用场景

从零搭建 SAPUI5/OpenUI5 应用
为已有 UI5 项目添加 CLI 支持
创建自定义构建任务或服务器中间件
搭建工作区/monorepo 管理多个相关 UI5 项目
从 UI5 CLI v3 迁移到 v4

限制与注意事项

不支持使用 import/export 语法的 JavaScript 模块，所有模块必须使用 sap.ui.define 格式。
模板字面量表达式不能用于依赖声明、Smart Template 名称和库初始化调用。
v4.0+ 中需要“顶层作用域”的 JavaScript 模块无法作为字符串打包，会被省略并记录错误。
对于 UI5 1.71，manifest 的 _version 属性必须 ≤ 1.17.0 才能生成 supportedLocales。
开发期间应使用 ui5 serve 而非 ui5 build，构建仅用于生产部署。
全局与本地 CLI 同时存在时本地版本优先，可用 UI5_CLI_NO_LOCAL=X 覆盖。
框架版本缓存于 ~/.ui5/，可通过 ui5DataDir 配置，清理命令为 rm -rf ~/.ui5/framework/。
环境变量：UI5_LOG_LVL、UI5_DATA_DIR、UI5_CLI_NO_LOCAL。

最佳实践

始终将 ui5.yaml 和 package.json 提交到版本控制；使用本地 CLI 安装（--save-dev）保证项目一致性；为生产构建固定框架版本；monorepo 使用工作区而非 npm link；开发时启用 HTTP/2（ui5 serve --h2）。