# SAPUI5/OpenUI5 CLI管理技巧 ## 目录 * 概述 * 何时使用此技能 * 快速启动工作流程 * 项目类型 * 捆绑资源 ## 概述此技能为使用 UI5 CLI（UI5 工具）提供全面的指导，UI5 CLI 是用于开发、构建和部署 SAPUI5 和 OpenUI5 应用程序和库的官方命令行界面。 **当前 CLI 版本**：4.0.0+（2024 年 7 月 24 日发布） **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.安装UI5 CLI（选择一项） npm install --global @ui5/cli # 全局安装 npm install --save-dev @ui5/cli # 项目级安装 # 2.初始化项目（如果是新的） npm init --yes # 初始化 npm ui5 init # 创建 ui5.yaml # 3. 选择框架变体 ui5 使用 openui5@latest # 对于 OpenUI5 ui5 使用 sapui5@latest # 对于 SAPUI5 # 4.添加框架库 ui5 添加 sap.ui.core sap.m sap.ui.table themelib_sap_fiori_3 # 5.开始开发 ui5serve # 启动开发服务器 ui5serve --open index.html # 启动并打开浏览器 # 6. 为生产而构建 ui5 build --all # 使用依赖项进行构建 ui5 build --clean-dest # 构建前清理 ### 现有项目设置 # 1.启用 CLI 支持用户界面5初始化 # 2.配置框架（如果ui5.yaml存在） ui5 使用 openui5@latest # 或 sapui5@latest # 3. 验证设置 ui5 tree # 显示依赖树 ui5serve # 测试开发服务器 ## 项目类型 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-types.md` ## 核心命令参考 ### 项目初始化 ui5 init # 初始化 UI5 CLI 配置 ui5 use [@version] # 设置框架(openui5/sapui5) ui5 add # 添加框架库 ui5 remove # 删除框架库 ### 发展 ui5serve [options] # 启动开发服务器 --port # 指定端口（默认：8080） --open # 打开浏览器到路径 --h2 # 启用 HTTP/2 --accept-remote-connections # 允许非本地主机访问 ui5 tree [options] # 显示依赖树 --flat # 显示平面列表 --level # 限制树深度 ### 建筑 ui5 build [child-command] [options] # 构建项目 preload # 创建预加载包（默认） self-contained # 创建独立包 jsdoc # 生成 JSDoc 文档 --all # 包含所有依赖项 --include-dependency # 包含特定的依赖项 --exclude-dependency # 排除依赖项 --dest # 输出目录（默认：./dist） --clean-dest # 构建前清理目标 --create-build-manifest # 存储构建元数据 --experimental-css-variables # 生成 CSS 变量工件 [实验] ### 配置 ui5 config set [value] # 设置配置值 ui5 config get # 获取配置值 ui5 config list # 列出所有设置 # 常用配置 ui5 config set ui5DataDir /path/.ui5 # 更改缓存目录 ### 实用程序 ui5 versions # 显示所有模块版本 ui5 --help # 显示帮助 ui5 --version # 显示版本有关完整命令参考，请参阅“references/cli-commands.md”。 ## 配置文件结构 ### 基本 ui5.yaml 结构 specVersion: "4.0" # 规范版本（必填） type: application # 项目类型（必填）元数据： name: my.project.name # 项目名称（必填）版权所有：“© ${currentYear} Company”# 可选版权框架：名称：SAPUI5 #OpenUI5 或 SAPUI5 version: "1.120.0" # 框架版本图书馆： - 名称：sap.ui.core - 名称：sap.m - 名称：sap.ui.table - 名称：themelib_sap_fiori_3 可选：true # 可选库资源：配置：路径： webapp: webapp # 路径映射 propertyFileSourceEncoding: UTF-8 # 编码（默认：UTF-8）建造者：资源：不包括： - "index.html" # 从构建中排除 -“/资源/我的/项目/测试/**” 服务器：设置： httpPort: 8080 # HTTP 端口 httpsPort: 8443 # HTTPS 端口完整的配置参考，请参见“references/configuration.md”。 ## 渐进式披露：详细参考资料该主要技能文件提供了基本的工作流程和快速参考。有关特定主题的详细信息，请参阅以下参考文件： ### 核心参考 * **`references/cli-commands.md`** ：包含所有选项和示例的完整 CLI 命令参考 * **`references/configuration.md`** ：综合 ui5.yaml 配置指南（包括工作区配置） * **`references/project-structs.md`** ：带有目录结构和构建输出样式的详细项目类型 ### 高级主题 * **`references/extensibility.md`** ：具有完整 API 文档的自定义任务、中间件和项目垫片 * **`references/filesystem-api.md`** : 用于自定义任务/中间件开发的完整文件系统 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. 启动开发服务器：`ui5serve` 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. 使用 ui5serve 进行测试 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 ` 标志激活特定工作区 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` 捆绑选项（如果存在） 5. 更新包部分以使用 `async: true` 进行现代加载 6. 测试构建：`ui5 build --all` 7. 测试服务器：`ui5serve` 8. 验证应用程序功能 ## 决策树 ### 框架选择决策 **问题**：我应该使用哪个框架？项目是否需要 SAP 特定组件（例如 sap.ui.comp、sap.ushell）？ ├─ 是 → 使用 SAPUI5 │ └─ 命令：ui5 use sapui5@latest └─ 否 → 可以使用OpenUI5 └─ 命令：ui5 use openui5@latest 注意：SAPUI5 项目可以依赖于 OpenUI5，但反之则不然。 ### 构建类型决策 **问题**：我应该使用哪种构建类型？部署目标是什么？ ├─ 标准部署（单独框架加载） │ └─ 使用：ui5 build --all │ ├─ 独立部署（与框架单一捆绑） │ └─ 使用：ui5构建自包含--all │ ├─ 文档生成 │ └─ 使用：ui5构建jsdoc │ └─ 开发/测试（无需构建） └─ 使用：ui5serve ### 自定义扩展决策 **问题**：我应该创建自定义任务或中间件吗？你需要扩展什么？ ├─ 构建过程（构建过程中修改/生成资源） │ └─ 创建自定义任务（参见 templates/custom-task-template.js） │ 示例：转译、图像优化、文件生成 │ ├─ 开发服务器（在开发期间修改请求/响应） │ └─ 创建自定义中间件（参见 templates/custom-middleware-template.js） │ 示例：代理、身份验证、动态内容 │ └─ 第三方库配置 └─ 创建项目垫片（参见references/extensibility.md）示例：配置非 UI5 npm 包 ## 模板该技能提供了常见配置的工作模板： * **`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.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** ：旧版本（尝试自动迁移）新项目始终使用最新的规范版本。 ### 框架版本要求 * **OpenUI5**：最低版本 1.52.5 * **SAPUI5**：最低版本 1.76.0 ### 开发与构建 **重要**：在开发过程中，始终使用“ui5serve”而不是“ui5build”。构建仅应在部署到生产时进行。开发服务器提供： * 更快的重新加载时间 * 即时资源处理 * 更好的调试体验 * 自动依赖解析 ### 全局安装与本地安装当全局和本地 UI5 CLI 安装同时存在时，本地版本自动优先。这允许不同的项目使用不同的 CLI 版本。覆盖行为：`UI5_CLI_NO_LOCAL=X ui5serve` ### 缓存管理 UI5 CLI 将框架版本缓存在 `~/.ui5/` 中（可通过 `ui5DataDir` 配置）。清除缓存：`rm -rf ~/.ui5/framework/` ## 已知问题和限制 ### ECMAScript 模块限制 UI5 CLI **不支持**具有“import”/“export”语法的 JavaScript 模块。所有模块必须使用“sap.ui.define”格式。 **不支持**：从'./module.js'导入模块；导出默认MyClass； **支持**： sap.ui.define(['./module'], 函数(模块) { 返回我的类； }); ### 模板文字限制模板文字中的表达式不能用于： * 依赖声明 * 智能模板名称 * 库初始化调用 **不支持**： sap.ui.define([`modules/${moduleName}`], ...); // 会失败 ### 捆绑限制 (v4.0+) 需要“顶级作用域”的 JavaScript 模块不能捆绑为字符串。它们将从带有错误日志记录的捆绑包中省略。 ### 清单版本兼容性对于 UI5 1.71，对于“supportedLocales”生成，清单“_version”属性必须 ≤ 1.17.0。更新清单版本以匹配 UI5 框架版本。 ## 故障排除快速参考有关详细的故障排除，请参阅“references/troubleshooting.md”。 ### 常见问题 **问题**：访问 HTTP 服务器时 Chrome 中的“ERR_SSL_PROTOCOL_ERROR” **解决方案**：Chrome 通过 HSTS 强制执行 HTTPS。清除 HSTS 设置： 1. 导航到“chrome://net-internals/#hsts” 2. 输入域名（例如 localhost） 3. 点击“删除” **问题**：`~/.ui5/` 中磁盘空间过多 **解决方案**：清除缓存的框架版本： rm -rf ~/.ui5/framework/ **问题**：构建失败并显示“TypeError：无效输入” **解决方案**：检查清单 `_version` 与 UI5 框架版本的兼容性。对于 UI5 1.71，请使用清单版本 ≤ 1.17.0。 **问题**：自定义任务未执行 **解决方案**：验证任务配置： 1. 检查任务是否在 ui5.yaml 中正确定义 2.验证`beforeTask`或`afterTask`引用有效的任务名称 3. 检查任务文件导出具有正确签名的异步函数 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=详细 ui5 构建 UI5_DATA_DIR=/custom/.ui5 ui5 服务 ## 最佳实践 1. **始终将 ui5.yaml 和 package.json** 提交到版本控制 2. **使用本地 CLI 安装**以保证项目一致性（`--save-dev`） 3. **为生产版本固定框架版本** 4. **使用工作区**进行 monorepo 设置而不是 npm 链接 5. **在开发期间启用 HTTP/2** (`ui5serve --h2`) 6. **干净构建**用于生产（`ui5 build --clean-dest --all`） 7. **在提交之前验证配置**（使用验证脚本） 8. **使用 CSP 策略时使用多个浏览器进行测试** 9. **在项目自述文件中记录自定义任务**和中间件 10. **保持 CLI 更新** 以受益于最新功能和修复 ## 其他资源 * **官方文档** : * **API参考**： * **JSON 架构** : * **GitHub 存储库**： * **SAP 社区**： * **npm 注册表** : ## 捆绑资源 ### 参考文档 * `references/cli-commands.md` \- 完整的 CLI 命令参考 * `references/configuration.md` \- 配置选项和 ui5.yaml * `references/project-structs.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/package.json.template` \- Package.json 模板 ## 版本信息 * **技能版本**：1.0.0 * **涵盖的 CLI 版本**：4.0.0+ * **最后更新** : 2025-11-21 * **下一次回顾** : 2026-02-21 (季刊) ** ** _此技能遵循官方 Anthropic Agent Skills 最佳实践和 SAP UI5 CLI 文档标准。_

萨普伊5命令行

包含技能