sapui5-cli

SAPUI5/OpenUI5 CLI 管理技能

相关技能

• sap-dependency-security：用于 UI5 工具工作流中的安全 CLI/工具链升级、锁文件加固和确定性安装

目录

• 概述
• 何时使用此技能
• 快速入门工作流
• 项目类型
• 打包资源

概述

此技能提供有关 UI5 CLI（UI5 Tooling）的全面指导。UI5 CLI 是用于开发、构建和部署 SAPUI5 与 OpenUI5 应用及库的官方命令行界面。

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

何时使用此技能

在需要执行以下操作时使用此技能：

• 初始化新的 UI5 项目，或为现有项目启用 CLI 支持
• 配置应用、库、主题库或模块的 ui5.yaml
• 构建带优化、打包和压缩的 UI5 项目
• 运行支持 HTTP/2、SSL 和 CSP 的本地开发服务器
• 使用自定义任务或服务器中间件扩展构建流程
• 管理包含多个 UI5 项目的 monorepo/工作区配置
• 排查常见的 UI5 CLI 错误和构建问题
• 迁移不同 CLI 版本（v1 → v2 → v3 → v4）
• 优化构建性能并分析依赖项

快速入门工作流

新建项目设置

# 1. Install UI5 CLI (choose one)
npm install --global @ui5/cli          # Global installation
npm install --save-dev @ui5/cli        # Project-level installation

# 2. Initialize project (if new)
npm init --yes                          # Initialize npm
ui5 init                                # Create ui5.yaml

# 3. Select framework variant
ui5 use openui5@latest                  # For OpenUI5
ui5 use sapui5@latest                   # For SAPUI5

# 4. Add framework libraries
ui5 add sap.ui.core sap.m sap.ui.table themelib_sap_fiori_3

# 5. Start development
ui5 serve                               # Start dev server
ui5 serve --open index.html            # Start and open browser

# 6. Build for production
ui5 build --all                         # Build with dependencies
ui5 build --clean-dest                  # Clean before building

现有项目设置

# 1. Enable CLI support
ui5 init

# 2. Configure framework (if ui5.yaml exists)
ui5 use openui5@latest                  # or sapui5@latest

# 3. Verify setup
ui5 tree                                # Show dependency tree
ui5 serve                               # Test development server

项目类型

UI5 CLI 支持四种项目类型，每种类型都有特定的配置：

1. 应用

带有 webapp 目录的标准 UI5 应用。

• 虚拟路径映射：webapp/ → /
• 存在 Component.js 时生成 Component-preload.js
• 配置模板见 templates/ui5.yaml.application

2. 库

可在多个项目间共享的可复用组件库。

• 虚拟路径映射：src/ → /resources，test/ → /test-resources
• 需要命名空间目录结构（例如 src/my/company/library/）
• 配置模板见 templates/ui5.yaml.library

3. 主题库

为库提供主题资源。

• 与标准库使用相同的虚拟路径映射
• 资源按命名空间组织（例如 my/library/themes/custom_theme/）
• 详细配置见 references/configuration.md

4. 模块

具有灵活路径映射的第三方资源。

• 资源会原样复制，不做修改
• 支持自定义虚拟路径到物理路径的映射
• 模块配置见 references/project-structures.md

核心命令参考

项目初始化

ui5 init                                # Initialize UI5 CLI configuration
ui5 use <framework>[@version]           # Set framework (openui5/sapui5)
ui5 add <libraries...>                  # Add framework libraries
ui5 remove <libraries...>               # Remove framework libraries

开发

ui5 serve [options]                     # Start development server
  --port <number>                       # Specify port (default: 8080)
  --open <path>                         # Open browser to path
  --h2                                  # Enable HTTP/2
  --accept-remote-connections           # Allow non-localhost access

ui5 tree [options]                      # Display dependency tree
  --flat                                # Show flat list
  --level <number>                      # Limit tree depth

构建

ui5 build [child-command] [options]     # Build project
  preload                               # Create preload bundles (default)
  self-contained                        # Create standalone bundle
  jsdoc                                 # Generate JSDoc documentation

  --all                                 # Include all dependencies
  --include-dependency <names>          # Include specific dependencies
  --exclude-dependency <names>          # Exclude dependencies
  --dest <path>                         # Output directory (default: ./dist)
  --clean-dest                          # Clean destination before build
  --create-build-manifest               # Store build metadata
  --experimental-css-variables          # Generate CSS variable artifacts [experimental]

配置

ui5 config set <key> [value]            # Set configuration value
ui5 config get <key>                    # Get configuration value
ui5 config list                         # List all settings

# Common configurations
ui5 config set ui5DataDir /path/.ui5    # Change cache directory

实用工具

ui5 versions                            # Display all module versions
ui5 --help                              # Display help
ui5 --version                           # Display version

完整命令参考请见 references/cli-commands.md。

配置文件结构

基本 ui5.yaml 结构

specVersion: "4.0"                      # Specification version (required)
type: application                       # Project type (required)
metadata:
  name: my.project.name                 # Project name (required)
  copyright: "© ${currentYear} Company" # Optional copyright

framework:
  name: SAPUI5                          # OpenUI5 or SAPUI5
  version: "1.120.0"                    # Framework version
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
    - name: themelib_sap_fiori_3
      optional: true                    # Optional library

resources:
  configuration:
    paths:
      webapp: webapp                    # Path mapping
    propertiesFileSourceEncoding: UTF-8 # Encoding (default: UTF-8)

builder:
  resources:
    excludes:
      - "index.html"                    # Exclude from build
      - "/resources/my/project/test/**"

server:
  settings:
    httpPort: 8080                      # HTTP port
    httpsPort: 8443                     # HTTPS port

完整配置参考请见 references/configuration.md。

渐进式披露：详细参考资料

此主要技能文件提供必要的工作流和快速参考。如需了解特定主题的详细信息，请参阅以下参考文件：

核心参考资料

• references/cli-commands.md：完整的 CLI 命令参考，包含所有选项和示例
• references/configuration.md：全面的 ui5.yaml 配置指南（包含工作区配置）
• references/project-structures.md：详细介绍项目类型、目录结构和构建输出样式

高级主题

• references/extensibility.md：自定义任务、中间件和项目 shim 的完整 API 文档
• references/filesystem-api.md：用于开发自定义任务／中间件的完整 FileSystem API
• references/build-process.md：完整的构建流程，包括任务、压缩、源映射和打包
• references/server-features.md：完整的服务文档，包括中间件堆栈、HTTP/2、SSL 和 CSP
• references/code-analysis.md：依赖分析器、JSDoc 生成和代码分析功能
• references/es-support.md：完整的 ECMAScript 版本支持、限制和模块格式要求

性能与故障排除

• references/benchmarking.md：使用 hyperfine 进行性能测试和基准测试
• references/migration-guides.md：完整的版本迁移指南（v1→v2→v3→v4）
• references/troubleshooting.md：常见问题、错误及解决方案，并附有准确的错误消息

常见工作流

工作流 1：设置新应用

适用场景：从头开始创建新的 SAPUI5/OpenUI5 应用。

步骤：

1. 初始化 npm 项目：npm init --yes
2. 安装 UI5 CLI：npm install --save-dev @ui5/cli
3. 初始化 UI5 配置：ui5 init
4. 选择框架：ui5 use sapui5@latest（或 openui5@latest）
5. 添加所需库：ui5 add sap.ui.core sap.m themelib_sap_fiori_3
6. 创建应用结构（webapp/、Component.js、manifest.json）
7. 启动开发服务器：ui5 serve
8. 提交配置：git add ui5.yaml package.json && git commit

工作流 2：为现有项目启用 CLI

适用场景：为现有 UI5 项目添加 UI5 CLI 支持。

步骤：

1. 导航到项目根目录
2. 运行 ui5 init 创建 ui5.yaml
3. 配置框架：ui5 use sapui5@latest
4. 添加库：ui5 add sap.ui.core sap.m sap.ui.table
5. 根据需要调整 ui5.yaml 中的 resources.configuration.paths
6. 使用 ui5 serve 测试
7. 使用 ui5 build --all 构建

工作流 3：创建自定义构建任务

适用场景：通过自定义处理扩展构建流程。

步骤：

1. 创建任务文件（例如 lib/tasks/customTask.js）
2. 使用 Task API 实现任务（参见 templates/custom-task-template.js）
3. 在 ui5.yaml 或单独的文件中创建任务扩展
4. 在 builder.customTasks 部分配置任务
5. 使用 ui5 build 测试
6. 详情请参见 references/extensibility.md

工作流 4：设置工作区／Monorepo

适用场景：在单个仓库中管理多个相关的 UI5 项目。

步骤：

1. 在项目根目录创建 ui5-workspace.yaml
2. 定义工作区名称和依赖解析规则
3. 使用相对路径指向本地项目目录
4. 使用 --workspace <name> 标志激活指定工作区
5. 运行 ui5 tree 验证依赖解析
6. 详情请参见 references/configuration.md（工作区部分）

工作流 5：迁移到 UI5 CLI v4

适用场景：从 UI5 CLI v3 升级到 v4。

先决条件：

• 确认 Node.js v20.11.0+ 或 v22.0.0+
• 确认 npm v8.0.0+

步骤：

1. 更新 CLI：npm install --save-dev @ui5/cli@latest
2. 将 ui5.yaml 中的 specVersion 更新为 "4.0"
3. 查看 references/migration-guides.md 中的破坏性变更
4. 如果存在 usePredefineCalls bundle 选项，则将其移除
5. 更新 bundle 部分，为现代加载方式使用 async: true
6. 测试构建：ui5 build --all
7. 测试服务：ui5 serve
8. 验证应用功能

决策树

框架选择决策

问题：我应该使用哪个框架？

Does project need SAP-specific components (e.g., sap.ui.comp, sap.ushell)?
├─ YES → Use SAPUI5
│  └─ Command: ui5 use sapui5@latest
└─ NO → Can use OpenUI5
   └─ Command: ui5 use openui5@latest

Note: SAPUI5 projects can depend on OpenUI5, but not vice versa.

构建类型决策

问题：我应该使用哪种构建类型？

What is the deployment target?
├─ Standard deployment (with separate framework loading)
│  └─ Use: ui5 build --all
│
├─ Standalone deployment (single bundle with framework)
│  └─ Use: ui5 build self-contained --all
│
├─ Documentation generation
│  └─ Use: ui5 build jsdoc
│
└─ Development/testing (no build needed)
   └─ Use: ui5 serve

自定义扩展决策

问题：我应该创建自定义任务还是中间件？

What do you need to extend?
├─ Build process (modify/generate resources during build)
│  └─ Create custom task (see templates/custom-task-template.js)
│     Examples: Transpiling, image optimization, file generation
│
├─ Development server (modify requests/responses during dev)
│  └─ Create custom middleware (see templates/custom-middleware-template.js)
│     Examples: Proxying, authentication, dynamic content
│
└─ Third-party library configuration
   └─ Create project shim (see references/extensibility.md)
      Examples: Configuring non-UI5 npm packages

模板

此技能提供常见配置的可用模板：

• templates/ui5.yaml.application：完整的应用配置
• templates/ui5.yaml.library：完整的库配置
• templates/ui5-workspace.yaml：Monorepo 工作区设置
• templates/custom-task-template.js：自定义构建任务样板
• templates/custom-middleware-template.js：自定义服务中间件样板

重要说明

规范版本

UI5 CLI 使用规范版本来管理功能：

• 4.0：当前主版本（已在 CLI v4.0.55 上验证，要求 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

开发与构建

重要：开发期间，请始终使用 ui5 serve，而不要使用 ui5 build。只有部署到生产环境时才应进行构建。开发服务器提供：

• 更快的重新加载速度
• 按需处理资源
• 更好的调试体验
• 自动解析依赖项

全局安装与本地安装

当全局和本地 UI5 CLI 安装同时存在时，会自动优先使用本地版本。这样，不同项目就可以使用不同的 CLI 版本。

覆盖此行为：UI5_CLI_NO_LOCAL=X ui5 serve

缓存管理

UI5 CLI 会在 ~/.ui5/ 中缓存框架版本（可通过 ui5DataDir 配置）。

清除缓存：rm -rf ~/.ui5/framework/

已知问题与限制

ECMAScript 模块限制

UI5 CLI 不支持使用 import/export 语法的 JavaScript 模块。所有模块都必须使用 sap.ui.define 格式。

不支持：

import Module from './module.js';
export default MyClass;

支持：

sap.ui.define(['./module'], function(Module) {
    return MyClass;
});

模板字面量限制

模板字面量中的表达式不能用于：

• 依赖项声明
• Smart Template 名称
• 库初始化调用

不支持：

sap.ui.define([`modules/${moduleName}`], ...);  // Will fail

打包限制（v4.0+）

需要“顶层作用域”的 JavaScript 模块不能打包为字符串。它们会被排除在打包文件之外，并记录错误日志。

Manifest 版本兼容性

对于 UI5 1.71，manifest 的 _version 属性必须 ≤ 1.17.0，才能生成 supportedLocales。请更新 manifest 版本，使其与 UI5 框架版本匹配。

故障排查速查

详细的故障排查信息请参阅 references/troubleshooting.md。

常见问题

问题：在 Chrome 中访问 HTTP 服务时出现 ERR_SSL_PROTOCOL_ERROR

解决方案：Chrome 会通过 HSTS 强制使用 HTTPS。请清除 HSTS 设置：

1. 前往 chrome://net-internals/#hsts
2. 输入域名（例如 localhost）
3. 点击“Delete”

问题：~/.ui5/ 占用过多磁盘空间

解决方案：清除缓存的框架版本：

rm -rf ~/.ui5/framework/

问题：构建失败，并显示“TypeError: invalid input”

解决方案：检查 manifest 的 _version 是否与 UI5 框架版本兼容。对于 UI5 1.71，请使用 ≤ 1.17.0 的 manifest 版本。

问题：自定义任务未执行

解决方案：检查任务配置：

1. 确认任务已在 ui5.yaml 中正确定义
2. 确认 beforeTask 或 afterTask 引用了有效的任务名称
3. 检查任务文件是否导出了签名正确的 async 函数
4. 使用 ui5 build --verbose 查看详细日志

环境变量

• UI5_LOG_LVL：设置日志级别（silent/error/warn/info/perf/verbose/silly）
• UI5_DATA_DIR：覆盖默认数据目录（~/.ui5）
• UI5_CLI_NO_LOCAL：禁用本地 CLI 优先级（使用全局版本）

示例：

UI5_LOG_LVL=verbose ui5 build
UI5_DATA_DIR=/custom/.ui5 ui5 serve

最佳实践

1. 始终将 ui5.yaml 和 package.json 提交到版本控制
2. 使用本地 CLI 安装以确保项目一致性（--save-dev）
3. 固定框架版本以用于生产构建
4. 在 monorepo 设置中使用工作区，而不是 npm 链接
5. 在开发期间启用 HTTP/2（ui5 serve --h2）
6. 执行干净构建以用于生产（ui5 build --clean-dest --all）
7. 在提交前验证配置（使用验证脚本）
8. 使用 CSP 策略时，使用多个浏览器进行测试
9. 在项目 README 中记录自定义任务和中间件
10. 保持 CLI 更新，以便使用最新功能和修复

其他资源

• 官方文档：https://ui5.github.io/cli/stable/
• API 参考：https://ui5.github.io/cli/v4/api/
• JSON Schema：https://ui5.github.io/cli/schema/ui5.yaml.json
• GitHub 仓库：https://github.com/SAP/ui5-tooling
• SAP 社区：https://community.sap.com/
• npm 注册表：https://www.npmjs.com/package/@ui5/cli

随附资源

参考文档

• references/cli-commands.md - 完整的 CLI 命令参考
• references/configuration.md - 配置选项和 ui5.yaml
• references/project-structures.md - 项目结构模式
• references/server-features.md - 开发服务器功能
• references/build-process.md - 构建流程和优化
• references/es-support.md - ES 模块支持
• references/extensibility.md - 可扩展性选项
• references/code-analysis.md - 代码分析工具
• references/migration-guides.md - 从旧版本迁移
• references/troubleshooting.md - 常见问题和解决方案
• references/benchmarking.md - 性能基准测试

模板

• templates/ui5.yaml.application - 应用程序配置模板
• templates/ui5.yaml.library - 库配置模板
• templates/ui5-workspace.yaml - 工作区配置模板
• templates/custom-task-template.js - 自定义任务样板
• templates/custom-middleware-template.js - 自定义中间件样板

版本信息

• 涵盖的 CLI 版本：4.0.55+
• 最后更新：2026-05-31
• 下次审查：2026-02-21（每季度）

---

此技能遵循 Anthropic Agent Skills 最佳实践和 SAP UI5 CLI 文档标准。