使用 UI5 Tooling CLI 管理…

在开发、构建、部署、扩展或迁移 SAPUI5/OpenUI5 应用、库、主题库或模块时，用 @ui5/cli 完成项目初始化、ui5.yaml 配置、开发服务器、构建优化、自定义任务/中间件、workspace 管理和故障排查。

适用场景

解决思路

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` 构建前清理目标目录。
7. 现有项目启用 CLI：进入项目根目录，运行 `ui5 init`，运行 `ui5 use openui5@latest` 或 `ui5 use sapui5@latest`，运行 `ui5 tree` 查看依赖树，运行 `ui5 serve` 测试开发服务器。
8. 配置 Application 类型：将 `webapp/` 映射到虚拟路径 `/`，存在 `Component.js` 时生成 `Component-preload.js`，参考 `templates/ui5.yaml.application`。
9. 配置 Library 类型：将 `src/` 映射到 `/resources`、`test/` 映射到 `/test-resources`，使用命名空间目录结构如 `src/my/company/library/`，参考 `templates/ui5.yaml.library`。
10. 配置 Theme Library 类型：使用与标准库相同的虚拟映射，按命名空间组织资源如 `my/library/themes/custom_theme/`，查阅 `references/configuration.md`。
11. 配置 Module 类型：资源按原样复制，设置自定义虚拟路径到物理路径映射，查阅 `references/project-structures.md`。
12. 项目初始化命令：运行 `ui5 init`、`ui5 use <framework>[@version]`、`ui5 add <libraries...>`、`ui5 remove <libraries...>`。
13. 开发服务器命令：运行 `ui5 serve [options]`，可用 `--port <number>` 指定端口，`--open <path>` 打开浏览器，`--h2` 启用 HTTP/2，`--accept-remote-connections` 允许非 localhost 访问。
14. 依赖树命令：运行 `ui5 tree [options]`，可用 `--flat` 显示扁平列表，`--level <number>` 限制树深度。
15. 构建命令：运行 `ui5 build [child-command] [options]`，子命令 `preload` 创建预加载包（默认）、`self-contained` 创建独立包、`jsdoc` 生成 JSDoc；选项 `--all` 包含所有依赖、`--include-dependency <names>` 包含指定依赖、`--exclude-dependency <names>` 排除指定依赖、`--dest <path>` 指定输出目录（默认 `./dist`）、`--clean-dest` 构建前清理目标、`--create-build-manifest` 存储构建元数据、`--experimental-css-variables` 生成 CSS 变量产物（实验性）。
16. 配置命令：运行 `ui5 config set <key> [value]`、`ui5 config get <key>`、`ui5 config list`；常用运行 `ui5 config set ui5DataDir /path/.ui5` 更改缓存目录。
17. 工具命令：运行 `ui5 versions` 显示所有模块版本，运行 `ui5 --help` 显示帮助，运行 `ui5 --version` 显示版本。
18. 编写基础 `ui5.yaml`：设置必填 `specVersion: "4.0"`、`type: application`、`metadata.name: my.project.name`；可选 `metadata.copyright`；设置 `framework.name` 为 `SAPUI5` 或 `OpenUI5`、`framework.version`、`framework.libraries` 列表和可选库 `optional: true`；设置 `resources.configuration.paths.webapp: webapp`、`propertiesFileSourceEncoding: UTF-8`；设置 `builder.resources.excludes` 排除 `index.html` 和 `/resources/my/project/test/**`；设置 `server.settings.httpPort: 8080`、`httpsPort: 8443`。
19. 查阅详细参考：需要完整 CLI 命令查 `references/cli-commands.md`，需要 ui5.yaml 配置查 `references/configuration.md`，需要项目结构查 `references/project-structures.md`，需要扩展查 `references/extensibility.md`，需要 FileSystem API 查 `references/filesystem-api.md`，需要构建过程查 `references/build-process.md`，需要服务器特性查 `references/server-features.md`，需要代码分析查 `references/code-analysis.md`，需要 ES 支持查 `references/es-support.md`，需要性能基准查 `references/benchmarking.md`，需要迁移查 `references/migration-guides.md`，需要排错查 `references/troubleshooting.md`。
20. 新建应用工作流：运行 `npm init --yes`；运行 `npm install --save-dev @ui5/cli`；运行 `ui5 init`；运行 `ui5 use sapui5@latest` 或 `ui5 use 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` 提交配置。
21. 现有项目工作流：进入项目根目录；运行 `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` 构建。
22. 创建自定义构建任务工作流：创建任务文件如 `lib/tasks/customTask.js`；使用 Task API 实现任务（参考 `templates/custom-task-template.js`）；在 `ui5.yaml` 或单独文件创建 task extension；在 `builder.customTasks` 段配置任务；运行 `ui5 build` 测试；细节查 `references/extensibility.md`。
23. 设置 Workspace/Monorepo 工作流：在根项目创建 `ui5-workspace.yaml`；定义 workspace 名称和依赖解析；用相对路径指向本地项目目录；运行命令时用 `--workspace <name>` 激活指定 workspace；运行 `ui5 tree` 验证依赖解析；细节查 `references/configuration.md` 的 workspace 部分。
24. 迁移到 UI5 CLI v4 工作流：验证 Node.js v20.11.0+ 或 v22.0.0+、npm v8.0.0+；运行 `npm install --save-dev @ui5/cli@latest` 更新 CLI；将 `ui5.yaml` 的 `specVersion` 更新为 `"4.0"`；查阅 `references/migration-guides.md` 的破坏性变更；移除 `usePredefineCalls` bundle 选项；将 bundle 段更新为使用 `async: true` 以支持现代加载；运行 `ui5 build --all` 测试构建；运行 `ui5 serve` 测试服务器；验证应用功能。
25. 选择框架：项目需要 SAP 特定组件如 `sap.ui.comp`、`sap.ushell` 时运行 `ui5 use sapui5@latest`；不需要时运行 `ui5 use openui5@latest`；注意 SAPUI5 项目可依赖 OpenUI5，反之不可。
26. 选择构建类型：标准部署运行 `ui5 build --all`；独立部署运行 `ui5 build self-contained --all`；文档生成运行 `ui5 build jsdoc`；开发/测试不构建，运行 `ui5 serve`。
27. 选择自定义扩展类型：构建过程中修改或生成资源时创建自定义 task（例：转译、图片优化、文件生成）；开发服务器修改请求/响应时创建自定义 middleware（例：代理、认证、动态内容）；配置第三方库时创建 project shim。
28. 使用模板：应用配置用 `templates/ui5.yaml.application`；库配置用 `templates/ui5.yaml.library`；monorepo 工作区用 `templates/ui5-workspace.yaml`；自定义构建任务用 `templates/custom-task-template.js`；自定义中间件用 `templates/custom-middleware-template.js`。
29. 管理规范版本：当前主版本为 `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`。
30. 满足框架版本要求：OpenUI5 最低版本 1.52.5，SAPUI5 最低版本 1.76.0。
31. 区分开发与构建：开发时始终运行 `ui5 serve` 而不是 `ui5 build`，仅在部署生产时构建；开发服务器提供更快重载、即时资源处理、更好调试、自动依赖解析。
32. 处理全局与本地安装：同时存在全局和本地 UI5 CLI 时本地版本自动优先；要覆盖该行为运行 `UI5_CLI_NO_LOCAL=X ui5 serve`。
33. 管理缓存：UI5 CLI 将框架版本缓存到 `~/.ui5/`，可通过 `ui5DataDir` 配置；清缓存运行 `rm -rf ~/.ui5/framework/`。
34. 遵守 ECMAScript 模块限制：不要使用 `import`/`export`，所有模块使用 `sap.ui.define` 格式，例如 `sap.ui.define(['./module'], function(Module) { return MyClass; });`。
35. 遵守模板字面量限制：不要在依赖声明、Smart Template 名称、库初始化调用中使用模板字面量表达式，例如不要写 `sap.ui.define([`modules/${moduleName}`], ...);`。
36. 遵守打包限制：v4.0+ 中需要 top level scope 的 JavaScript 模块不能作为字符串打包，会被从 bundle 中省略并记录错误。
37. 处理 manifest 版本兼容：UI5 1.71 中 manifest `_version` 必须 ≤ 1.17.0 才能生成 `supportedLocales`；将 manifest 版本更新到与 UI5 框架版本匹配。
38. 排错 `ERR_SSL_PROTOCOL_ERROR`：Chrome 因 HSTS 强制 HTTPS；访问 `chrome://net-internals/#hsts`，输入域名如 `localhost`，点击 Delete。
39. 排错 `~/.ui5/` 磁盘占用过大：运行 `rm -rf ~/.ui5/framework/` 清理缓存框架版本。
40. 排错构建失败 `TypeError: invalid input`：检查 manifest `_version` 与 UI5 框架版本兼容；UI5 1.71 使用 manifest 版本 ≤ 1.17.0。
41. 排错自定义任务不执行：检查任务在 `ui5.yaml` 中正确定义；验证 `beforeTask` 或 `afterTask` 引用有效任务名；检查任务文件导出具有正确签名的 async 函数；运行 `ui5 build --verbose` 获取详细日志。
42. 使用环境变量：设置 `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`。
43. 遵循最佳实践：始终将 `ui5.yaml` 和 `package.json` 提交到版本控制；项目中使用本地 CLI 安装以保持一致（`--save-dev`）；生产构建固定框架版本；monorepo 使用 workspaces 而不是 npm linking；开发时启用 HTTP/2（`ui5 serve --h2`）；生产使用干净构建（`ui5 build --clean-dest --all`）；提交前验证配置；使用 CSP 时多浏览器测试；在项目 README 中记录自定义任务和 middleware；保持 CLI 更新以获取最新功能和修复。
44. 相关安全做法：在 UI5 tooling 工作流中需要安全升级 CLI/toolchain、加固 lockfile、确定性安装时，参考 `sap-dependency-security` 技能。
45. 查阅官方资源：官方文档 `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 Community `https://community.sap.com/`，npm Registry `https://www.npmjs.com/package/@ui5/cli`。

适用边界 · 注意事项

• 不适用于非 SAPUI5/OpenUI5 项目，或不需要 UI5 Tooling/@ui5/cli 的普通前端项目。
• 不适用于 Node.js v21；该 CLI 要求 Node.js v20.11.0+ 或 v22.0.0+，npm v8.0.0+。
• 不适用于必须使用原生 ES module import/export 的项目；UI5 CLI 不支持，需要改用 sap.ui.define 等受支持写法。