sapui5-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAPUI5/OpenUI5 CLI Management Skill

SAPUI5/OpenUI5 CLI 管理技能

Overview

概述

This skill provides comprehensive guidance for working with the UI5 CLI (UI5 Tooling), the official command-line interface for developing, building, and deploying SAPUI5 and OpenUI5 applications and libraries.

Current CLI Version: 4.0.0+ (Released July 24, 2024) Node.js Requirements: v20.11.0+ or v22.0.0+ (v21 not supported) npm Requirements: v8.0.0+

本技能为使用UI5 CLI（UI5 Tooling）提供全面指导，UI5 CLI是开发、构建、部署SAPUI5和OpenUI5应用及库的官方命令行工具。

当前CLI版本：4.0.0+（2024年7月24日发布） Node.js 要求：v20.11.0+ 或 v22.0.0+（不支持v21） npm 要求：v8.0.0+

When to Use This Skill

何时使用本技能

Use this skill when you need to:

Initialize new UI5 projects or enable CLI support for existing projects
Configure ui5.yaml for applications, libraries, theme-libraries, or modules
Build UI5 projects with optimization, bundling, and minification
Run local development servers with HTTP/2, SSL, and CSP support
Extend build processes with custom tasks or server middleware
Manage monorepo/workspace configurations with multiple UI5 projects
Troubleshoot common UI5 CLI errors and build issues
Migrate between CLI versions (v1 → v2 → v3 → v4)
Optimize build performance and analyze dependencies

当你需要完成以下操作时可使用本技能：

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

Quick Start Workflow

快速入门流程

New Project Setup

新项目设置

bash

undefined

bash

undefined

1. Install UI5 CLI (choose one)

1. 安装UI5 CLI（二选一）

npm install --global @ui5/cli # Global installation npm install --save-dev @ui5/cli # Project-level installation

npm install --global @ui5/cli # 全局安装 npm install --save-dev @ui5/cli # 项目级安装

2. Initialize project (if new)

2. 初始化项目（如果是新项目）

npm init --yes # Initialize npm ui5 init # Create ui5.yaml

npm init --yes # 初始化npm项目 ui5 init # 创建ui5.yaml

3. Select framework variant

3. 选择框架版本

ui5 use openui5@latest # For OpenUI5 ui5 use sapui5@latest # For SAPUI5

ui5 use openui5@latest # 选择OpenUI5 ui5 use sapui5@latest # 选择SAPUI5

4. Add framework libraries

4. 添加框架依赖库

ui5 add sap.ui.core sap.m sap.ui.table themelib_sap_fiori_3

5. Start development

5. 启动开发

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

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

6. Build for production

6. 生产环境构建

ui5 build --all # Build with dependencies ui5 build --clean-dest # Clean before building

undefined

ui5 build --all # 包含所有依赖的构建 ui5 build --clean-dest # 构建前清空输出目录

undefined

Existing Project Setup

现有项目设置

bash

undefined

bash

undefined

1. Enable CLI support

1. 启用CLI支持

ui5 init

2. Configure framework (if ui5.yaml exists)

2. 配置框架（如果已存在ui5.yaml）

ui5 use openui5@latest # or sapui5@latest

ui5 use openui5@latest # 或 sapui5@latest

3. Verify setup

3. 验证配置

ui5 tree # Show dependency tree ui5 serve # Test development server

undefined

ui5 tree # 显示依赖树 ui5 serve # 测试开发服务器

undefined

Project Types

项目类型

UI5 CLI supports four project types, each with specific configurations:

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

1. Application

1. 应用

Standard UI5 applications with a

webapp

directory.

Virtual path mapping:
```
webapp/
```
→
```
/
```
Generates Component-preload.js when Component.js exists
See
```
templates/ui5.yaml.application
```
for configuration template

标准UI5应用，包含

webapp

目录。

虚拟路径映射：
```
webapp/
```
→
```
/
```
存在Component.js时会自动生成Component-preload.js
配置模板可参考
```
templates/ui5.yaml.application
```

2. Library

2. 库

Reusable component libraries for sharing across projects.

Virtual path mappings:
```
src/
```
→
```
/resources
```
,
```
test/
```
→
```
/test-resources
```
Requires namespace directory structure (e.g.,
```
src/my/company/library/
```
)
See
```
templates/ui5.yaml.library
```
for configuration template

可复用的组件库，可跨项目共享。

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

3. Theme Library

3. 主题库

Provides theming resources for libraries.

Same virtual mappings as standard libraries
Resources organized by namespace (e.g.,
```
my/library/themes/custom_theme/
```
)
See
```
references/configuration.md
```
for detailed configuration

为库提供主题资源。

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

4. Module

4. 模块

Third-party resources with flexible path mapping.

Resources copied without modification
Custom virtual-to-physical path mappings
See
```
references/project-types.md
```
for module configuration

第三方资源，支持灵活的路径映射。

资源会原封不动地复制
支持自定义虚拟路径到物理路径的映射
模块配置可参考
```
references/project-types.md
```

Core Commands Reference

核心命令参考

Project Initialization

项目初始化

bash

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

bash

ui5 init                                # 初始化UI5 CLI配置
ui5 use <framework>[@version]           # 设置框架（openui5/sapui5）
ui5 add <libraries...>                  # 添加框架依赖库
ui5 remove <libraries...>               # 移除框架依赖库

Development

开发相关

bash

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

bash

ui5 serve [options]                     # 启动开发服务器
  --port <number>                       # 指定端口（默认：8080）
  --open <path>                         # 打开浏览器到指定路径
  --h2                                  # 启用HTTP/2
  --accept-remote-connections           # 允许非localhost访问

ui5 tree [options]                      # 显示依赖树
  --flat                                # 显示平铺列表
  --level <number>                      # 限制树的层级深度

Building

构建相关

bash

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]

bash

ui5 build [child-command] [options]     # 构建项目
  preload                               # 创建preload包（默认）
  self-contained                        # 创建独立包
  jsdoc                                 # 生成JSDoc文档

  --all                                 # 包含所有依赖
  --include-dependency <names>          # 包含指定依赖
  --exclude-dependency <names>          # 排除指定依赖
  --dest <path>                         # 输出目录（默认：./dist）
  --clean-dest                          # 构建前清空目标目录
  --create-build-manifest               # 存储构建元数据
  --experimental-css-variables          # 生成CSS变量产物[实验性特性]

Configuration

配置相关

bash

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

bash

ui5 config set <key> [value]            # 设置配置值
ui5 config get <key>                    # 获取配置值
ui5 config list                         # 列出所有配置项

Common configurations

常见配置

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

undefined

ui5 config set ui5DataDir /path/.ui5 # 修改缓存目录

undefined

Utility

工具命令

bash

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

For complete command reference, see

references/cli-commands.md

bash

ui5 versions                            # 显示所有模块版本
ui5 --help                              # 显示帮助信息
ui5 --version                           # 显示版本号

完整的命令参考可查看

references/cli-commands.md

。

Configuration File Structure

配置文件结构

Basic ui5.yaml Structure

基础ui5.yaml结构

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

For complete configuration reference, see

references/configuration.md

yaml

specVersion: "4.0"                      # 规范版本（必填）
type: application                       # 项目类型（必填）
metadata:
  name: my.project.name                 # 项目名称（必填）
  copyright: "© ${currentYear} Company" # 可选版权信息

framework:
  name: SAPUI5                          # OpenUI5 或 SAPUI5
  version: "1.120.0"                    # 框架版本
  libraries:
    - name: sap.ui.core
    - name: sap.m
    - name: sap.ui.table
    - name: themelib_sap_fiori_3
      optional: true                    # 可选依赖库

resources:
  configuration:
    paths:
      webapp: webapp                    # 路径映射
    propertiesFileSourceEncoding: UTF-8 # 编码格式（默认：UTF-8）

builder:
  resources:
    excludes:
      - "index.html"                    # 构建时排除
      - "/resources/my/project/test/**"

server:
  settings:
    httpPort: 8080                      # HTTP端口
    httpsPort: 8443                     # HTTPS端口

完整的配置参考可查看

references/configuration.md

。

Progressive Disclosure: Detailed References

渐进式参考：详细文档

This main skill file provides essential workflows and quick reference. For detailed information on specific topics, refer to these reference files:

本主技能文件提供了核心流程和快速参考，特定主题的详细信息可参考以下文档：

Core References

核心参考

references/cli-commands.md
: Complete CLI command reference with all options and examples
references/configuration.md
: Comprehensive ui5.yaml configuration guide (includes workspace config)
references/project-structures.md
: Detailed project types with directory structures and build output styles

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

Advanced Topics

高级主题

references/extensibility.md
: Custom tasks, middleware, and project shims with complete API documentation
references/filesystem-api.md
: Complete FileSystem API for custom task/middleware development
references/build-process.md
: Complete build process including tasks, minification, source maps, and bundling
references/server-features.md
: Complete server documentation with middleware stack, HTTP/2, SSL, and CSP
references/code-analysis.md
: Dependency analyzers, JSDoc generation, and code analysis features
references/es-support.md
: Complete ECMAScript version support, restrictions, and module format requirements

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

Performance & Troubleshooting

性能与排障

references/benchmarking.md
: Performance testing and benchmarking with hyperfine
references/migration-guides.md
: Complete version migration guides (v1→v2→v3→v4)
references/troubleshooting.md
: Common issues, errors, and solutions with exact error messages

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

Common Workflows

常见工作流

Workflow 1: Setting Up a New Application

工作流1：新建应用设置

When to use: Starting a new SAPUI5/OpenUI5 application from scratch.

Steps:

Initialize npm project:
```
npm init --yes
```
Install UI5 CLI:
```
npm install --save-dev @ui5/cli
```
Initialize UI5 configuration:
```
ui5 init
```
Select framework:
```
ui5 use sapui5@latest
```
(or
```
openui5@latest
```
)

Add required libraries:

ui5 add sap.ui.core sap.m themelib_sap_fiori_3

Create application structure (webapp/, Component.js, manifest.json)
Start development server:
```
ui5 serve
```

Commit configuration:

git add ui5.yaml package.json && git commit

适用场景：从零开始启动新的SAPUI5/OpenUI5应用。

步骤：

初始化npm项目：
```
npm init --yes
```
安装UI5 CLI：
```
npm install --save-dev @ui5/cli
```
初始化UI5配置：
```
ui5 init
```
选择框架：
```
ui5 use sapui5@latest
```
（或
```
openui5@latest
```
）

添加所需依赖库：

ui5 add sap.ui.core sap.m themelib_sap_fiori_3

创建应用结构（webapp/、Component.js、manifest.json）
启动开发服务器：
```
ui5 serve
```

提交配置：

git add ui5.yaml package.json && git commit

Workflow 2: Enabling CLI for Existing Project

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

When to use: Adding UI5 CLI support to an existing UI5 project.

Steps:

Navigate to project root
Run
```
ui5 init
```
to create ui5.yaml
Configure framework:
```
ui5 use sapui5@latest
```
Add libraries:
```
ui5 add sap.ui.core sap.m sap.ui.table
```
Adjust ui5.yaml
```
resources.configuration.paths
```
if needed
Test with
```
ui5 serve
```
Build with
```
ui5 build --all
```

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

步骤：

进入项目根目录
运行
```
ui5 init
```
创建ui5.yaml
配置框架：
```
ui5 use sapui5@latest
```
添加依赖库：
```
ui5 add sap.ui.core sap.m sap.ui.table
```
按需调整ui5.yaml的
```
resources.configuration.paths
```
配置
运行
```
ui5 serve
```
测试
运行
```
ui5 build --all
```
构建测试

Workflow 3: Creating a Custom Build Task

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

When to use: Extending the build process with custom processing.

Steps:

Create task file (e.g.,
```
lib/tasks/customTask.js
```
)
Implement task using Task API (see
```
templates/custom-task-template.js
```
)
Create task extension in ui5.yaml or separate file
Configure task in builder.customTasks section
Test with
```
ui5 build
```
For details, see
```
references/extensibility.md
```

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

步骤：

创建任务文件（例如
```
lib/tasks/customTask.js
```
）
使用任务API实现任务逻辑（参考
```
templates/custom-task-template.js
```
）
在ui5.yaml或单独文件中创建任务扩展
在builder.customTasks部分配置任务
运行
```
ui5 build
```
测试
详情可参考
```
references/extensibility.md
```

Workflow 4: Setting Up a Workspace/Monorepo

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

When to use: Managing multiple related UI5 projects in a single repository.

Steps:

Create ui5-workspace.yaml in root project
Define workspace name and dependency resolutions
Point to local project directories using relative paths
Use
```
--workspace <name>
```
flag to activate specific workspace
Run
```
ui5 tree
```
to verify dependency resolution
For details, see
```
references/configuration.md
```
(workspace section)

适用场景：在单个代码库中管理多个关联的UI5项目。

步骤：

在根项目中创建ui5-workspace.yaml
定义工作区名称和依赖解析规则
使用相对路径指向本地项目目录
使用
```
--workspace <name>
```
参数激活指定工作区
运行
```
ui5 tree
```
验证依赖解析是否正确
详情可参考
```
references/configuration.md
```
（工作区部分）

Workflow 5: Migrating to UI5 CLI v4

工作流5：迁移到UI5 CLI v4

When to use: Upgrading from UI5 CLI v3 to v4.

Prerequisites:

Verify Node.js v20.11.0+ or v22.0.0+
Verify npm v8.0.0+

Steps:

Update CLI:
```
npm install --save-dev @ui5/cli@latest
```
Update specVersion in ui5.yaml to
```
"4.0"
```
Review breaking changes in
```
references/migration-guides.md
```
Remove
```
usePredefineCalls
```
bundle option if present
Update bundle sections to use
```
async: true
```
for modern loading
Test build:
```
ui5 build --all
```
Test server:
```
ui5 serve
```
Verify application functionality

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

前置要求：

确认Node.js版本为v20.11.0+ 或 v22.0.0+
确认npm版本为v8.0.0+

步骤：

更新CLI：
```
npm install --save-dev @ui5/cli@latest
```
将ui5.yaml中的specVersion更新为
```
"4.0"
```
查看
```
references/migration-guides.md
```
中的破坏性变更
移除存在的
```
usePredefineCalls
```
打包选项
更新打包配置，使用
```
async: true
```
启用现代加载方式
测试构建：
```
ui5 build --all
```
测试服务器：
```
ui5 serve
```
验证应用功能是否正常

Decision Trees

决策树

Framework Selection Decision

框架选择决策

Question: Which framework should I use?

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.

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

项目是否需要SAP专属组件（例如sap.ui.comp、sap.ushell）？
├─ 是 → 使用SAPUI5
│  └─ 命令：ui5 use sapui5@latest
└─ 否 → 可使用OpenUI5
   └─ 命令：ui5 use openui5@latest

注意：SAPUI5项目可以依赖OpenUI5，但反之不成立。

Build Type Decision

构建类型决策

Question: Which build type should I use?

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

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

部署目标是什么？
├─ 标准部署（单独加载框架）
│  └─ 使用：ui5 build --all
│
├─ 独立部署（包含框架的单包）
│  └─ 使用：ui5 build self-contained --all
│
├─ 生成文档
│  └─ 使用：ui5 build jsdoc
│
└─ 开发/测试（无需构建）
   └─ 使用：ui5 serve

Custom Extension Decision

自定义扩展决策

Question: Should I create a custom task or middleware?

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/custom-task-template.js）
│     示例：转译、图片优化、文件生成
│
├─ 开发服务器（开发过程中修改请求/响应）
│  └─ 创建自定义中间件（参考templates/custom-middleware-template.js）
│     示例：代理、身份认证、动态内容
│
└─ 第三方库配置
   └─ 创建项目垫片（参考references/extensibility.md）
      示例：配置非UI5的npm包

Templates

模板

This skill provides working templates for common configurations:

templates/ui5.yaml.application
: Complete application configuration
templates/ui5.yaml.library
: Complete library configuration
templates/ui5-workspace.yaml
: Monorepo workspace setup
templates/custom-task-template.js
: Custom build task boilerplate
templates/custom-middleware-template.js
: Custom server middleware boilerplate

本技能提供了常用配置的可用模板：

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

Important Notes

重要注意事项

Specification Versions

规范版本

UI5 CLI uses specification versions to manage features:

4.0: Current version (requires CLI v4.0.0+, Node.js v20.11.0+)
3.0-3.2: Compatible with CLI v3.0.0+
2.0-2.6: Compatible with CLI v2.0.0+
0.1-1.1: Legacy versions (automatic migration attempted)

Always use the latest specVersion for new projects.

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

4.0：当前版本（要求CLI v4.0.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： legacy版本（会尝试自动迁移）

新项目请始终使用最新的specVersion。

Framework Version Requirements

框架版本要求

OpenUI5: Minimum version 1.52.5
SAPUI5: Minimum version 1.76.0

OpenUI5：最低版本1.52.5
SAPUI5：最低版本1.76.0

Development vs. Build

开发 vs 构建

Important: During development, always use

ui5 serve

instead of

ui5 build

. Building should only occur when deploying to production. The development server provides:

Faster reload times
On-the-fly resource processing
Better debugging experience
Automatic dependency resolution

重要提示：开发过程中请始终使用

ui5 serve

而非

ui5 build

。仅在部署到生产环境时才需要构建。开发服务器提供：

更快的重载速度
实时资源处理
更好的调试体验
自动依赖解析

Global vs. Local Installation

全局 vs 本地安装

When both global and local UI5 CLI installations exist, the local version takes precedence automatically. This allows different projects to use different CLI versions.

Override behavior:

UI5_CLI_NO_LOCAL=X ui5 serve

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

覆盖默认行为：

UI5_CLI_NO_LOCAL=X ui5 serve

Cache Management

缓存管理

UI5 CLI caches framework versions in

~/.ui5/

(configurable via

ui5DataDir

Clear cache:

rm -rf ~/.ui5/framework/

UI5 CLI将框架版本缓存到

~/.ui5/

（可通过

ui5DataDir

配置）。

清空缓存：

rm -rf ~/.ui5/framework/

Known Issues & Limitations

已知问题与限制

ECMAScript Module Limitations

ECMAScript模块限制

UI5 CLI does not support JavaScript modules with

import

export

syntax. All modules must use

sap.ui.define

format.

Unsupported:

javascript

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

Supported:

javascript

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

UI5 CLI 不支持 使用

import

export

语法的JavaScript模块。所有模块必须使用

sap.ui.define

格式。

不支持：

javascript

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

支持：

javascript

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

Template Literal Restrictions

模板字面量限制

Expressions in template literals cannot be used in:

Dependency declarations
Smart Template names
Library initialization calls

Unsupported:

javascript

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

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

依赖声明
智能模板名称
库初始化调用

不支持：

javascript

sap.ui.define([`modules/${moduleName}`], ...);  // 会执行失败

Bundling Restrictions (v4.0+)

打包限制（v4.0+）

JavaScript modules requiring 'top level scope' cannot be bundled as strings. They will be omitted from bundles with error logging.

需要“顶层作用域”的JavaScript模块不能作为字符串打包，会从包中省略并输出错误日志。

Manifest Version Compatibility

Manifest版本兼容性

For UI5 1.71, manifest

_version

property must be ≤ 1.17.0 for

supportedLocales

generation. Update manifest version to match UI5 framework version.

对于UI5 1.71，manifest的

_version

属性必须 ≤ 1.17.0才能生成

supportedLocales

。请更新manifest版本以匹配UI5框架版本。

Troubleshooting Quick Reference

排障快速参考

For detailed troubleshooting, see

references/troubleshooting.md

详细排障指南可查看

references/troubleshooting.md

。

Common Issues

常见问题

Issue:

ERR_SSL_PROTOCOL_ERROR

in Chrome when accessing HTTP server

Solution: Chrome enforces HTTPS via HSTS. Clear HSTS settings:

Navigate to
```
chrome://net-internals/#hsts
```
Enter domain (e.g., localhost)
Click "Delete"

Issue: Excessive disk space in

~/.ui5/

Solution: Clear cached framework versions:

bash

rm -rf ~/.ui5/framework/

Issue: Build fails with "TypeError: invalid input"

Solution: Check manifest

_version

compatibility with UI5 framework version. For UI5 1.71, use manifest version ≤ 1.17.0.

Issue: Custom task not executing

Solution: Verify task configuration:

Check task is properly defined in ui5.yaml
Verify
```
beforeTask
```
or
```
afterTask
```
references valid task name
Check task file exports async function with correct signature
Use
```
ui5 build --verbose
```
for detailed logging

问题：访问HTTP服务器时Chrome报

ERR_SSL_PROTOCOL_ERROR

解决方案：Chrome通过HSTS强制使用HTTPS，需清空HSTS设置：

打开
```
chrome://net-internals/#hsts
```
输入域名（例如localhost）
点击“Delete”

问题：

~/.ui5/

占用过多磁盘空间

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

bash

rm -rf ~/.ui5/framework/

问题：构建失败，报错“TypeError: invalid input”

解决方案：检查manifest的

_version

与UI5框架版本的兼容性。对于UI5 1.71，请使用≤1.17.0的manifest版本。

问题：自定义任务不执行

解决方案：验证任务配置：

确认任务已在ui5.yaml中正确定义
确认
```
beforeTask
```
或
```
afterTask
```
引用的是有效任务名称
确认任务文件导出的是签名正确的异步函数
使用
```
ui5 build --verbose
```
获取详细日志

Environment Variables

环境变量

UI5_LOG_LVL
: Set log level (silent/error/warn/info/perf/verbose/silly)
UI5_DATA_DIR
: Override default data directory (~/.ui5)
UI5_CLI_NO_LOCAL
: Disable local CLI precedence (use global)

Examples:

bash

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

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

示例：

bash

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

Best Practices

最佳实践

Always commit ui5.yaml and package.json to version control
Use local CLI installation for project consistency (
```
--save-dev
```
)
Pin framework versions for production builds
Use workspaces for monorepo setups instead of npm linking
Enable HTTP/2 during development (
```
ui5 serve --h2
```
)
Clean builds for production (
```
ui5 build --clean-dest --all
```
)
Validate configurations before committing (use validation scripts)
Test with multiple browsers when using CSP policies
Document custom tasks and middleware in project README
Keep CLI updated to benefit from latest features and fixes

始终将ui5.yaml和package.json提交到版本控制
使用本地CLI安装保证项目一致性（
```
--save-dev
```
）
固定框架版本用于生产构建
使用工作区管理monorepo设置，而非npm link
开发时启用HTTP/2（
```
ui5 serve --h2
```
）
生产环境使用干净构建（
```
ui5 build --clean-dest --all
```
）
提交前验证配置（使用验证脚本）
使用CSP策略时在多个浏览器中测试
在项目README中记录自定义任务和中间件
保持CLI更新以获取最新功能和修复

Additional Resources

额外资源

Official Documentation: https://ui5.github.io/cli/stable/
API Reference: https://ui5.github.io/cli/v4/api/
JSON Schema: https://ui5.github.io/cli/schema/ui5.yaml.json
GitHub Repository: https://github.com/SAP/ui5-tooling
SAP Community: https://community.sap.com/
npm Registry: https://www.npmjs.com/package/@ui5/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 Registry：https://www.npmjs.com/package/@ui5/cli

Bundled Resources

附带资源

Reference Documentation

参考文档

```
references/cli-commands.md
```
- Complete CLI command reference
```
references/configuration.md
```
- Configuration options and ui5.yaml
```
references/project-structures.md
```
- Project structure patterns
```
references/server-features.md
```
- Development server features
```
references/build-process.md
```
- Build process and optimization
```
references/es-support.md
```
- ES module support
```
references/extensibility.md
```
- Extensibility options
```
references/code-analysis.md
```
- Code analysis tools
```
references/migration-guides.md
```
- Migration from older versions
```
references/troubleshooting.md
```
- Common issues and solutions
```
references/benchmarking.md
```
- Performance benchmarking

```
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

模板

```
templates/package.json.template
```
- Package.json template

```
templates/package.json.template
```
- Package.json模板

Version Information

版本信息

Skill Version: 1.0.0
CLI Version Covered: 4.0.0+
Last Updated: 2025-11-21
Next Review: 2026-02-21 (Quarterly)

This skill follows official Anthropic Agent Skills best practices and SAP UI5 CLI documentation standards.

技能版本：1.0.0
覆盖CLI版本：4.0.0+
最后更新：2025-11-21
下次评审：2026-02-21（每季度）

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

sapui5-cli

Original

Translation

SAPUI5/OpenUI5 CLI Management Skill

SAPUI5/OpenUI5 CLI 管理技能

Table of Contents

目录

Overview

概述

When to Use This Skill

何时使用本技能

Quick Start Workflow

快速入门流程

New Project Setup

新项目设置

1. Install UI5 CLI (choose one)

1. 安装UI5 CLI（二选一）

2. Initialize project (if new)

2. 初始化项目（如果是新项目）

3. Select framework variant

3. 选择框架版本

4. Add framework libraries

4. 添加框架依赖库

5. Start development

5. 启动开发

6. Build for production

6. 生产环境构建

Existing Project Setup

现有项目设置

1. Enable CLI support

1. 启用CLI支持

2. Configure framework (if ui5.yaml exists)

2. 配置框架（如果已存在ui5.yaml）

3. Verify setup

3. 验证配置

Project Types

项目类型

1. Application

1. 应用

2. Library

2. 库

3. Theme Library

3. 主题库

4. Module

4. 模块

Core Commands Reference

核心命令参考

Project Initialization

项目初始化

Development

开发相关

Building

构建相关

Configuration

配置相关

Common configurations

常见配置

Utility

工具命令

Configuration File Structure

配置文件结构

Basic ui5.yaml Structure

基础ui5.yaml结构

Progressive Disclosure: Detailed References

渐进式参考：详细文档

Core References

核心参考

Advanced Topics

高级主题

Performance & Troubleshooting

性能与排障

Common Workflows

常见工作流

Workflow 1: Setting Up a New Application

工作流1：新建应用设置

Workflow 2: Enabling CLI for Existing Project

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

Workflow 3: Creating a Custom Build Task

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

Workflow 4: Setting Up a Workspace/Monorepo