企业官网建设流程全解析

这几年做 SAP 前端的朋友，十有八九都问过同样一个问题：能不能不在 SAP 自家的 Web IDE 或者 BAS 里写 Fiori，而是直接用 vscode 把代码撸起来？答案是能，而且官方这条路走得比很多人想象中要完整得多。SAP Fiori Tools 这套官方扩展装进 vscode 之后，从项目脚手架、OData 服务连接，到本地预览、断点调试、一键部署，整条链路都能在本地编辑器里跑通。这套方案尤其适合习惯现代前端工作流、想在轻量环境里写 SAPUI5 代码的开发者——不用开浏览器云 IDE，不用等远程编译，本地 npm 起服务，几秒钟就能看到界面改动。这篇文章就把我从零折腾 vscode + Fiori 的全过程、踩过的坑和最终沉淀下来的可靠配置，一次讲清楚。

1. 为什么要在 VSCode 里开发 Fiori

1.1 Fiori 开发到底依赖什么样的工具链

SAP Fiori 本质上是 SAP 提出的那套企业级 UI 设计规范，落到技术层面，绝大多数 Fiori 应用就是跑在 SAPUI5 这棵前端框架树上的 Web 应用。按组件上又是控件库，比如我们最熟悉的 sap.m、sap.f、sap.ui.table 这些，全都是在浏览器端渲染，通过 OData 协议跟后端 ABAP 服务或者 S/4HANA Cloud 通讯。

所以要开发 Fiori 应用，最少得有这几样东西：一个能编辑 JavaScript/XML 的编辑器、一个能构建和启动本地服务的运行时、一个能把 OData 服务连回来的代理通道，以及一个能下断点调页面的调试工具。传统做法是直接用 SAP 自家的 Web IDE。Web IDE 确实什么都有，但它在浏览器里跑，项目一大就卡，而且编辑器本体比较笨重。后来 SAP 把主推迁移到 Business Application Studio（BAS），云 IDE 能力更强了，但还是那个问题：没有本地开发那种轻快感，打开面板环境、等云端工作区就绪，都要花时间。

1.2 VSCode 方案到底解决了什么痛点

VSCode 这套方案最大的价值，是把你从“必须用某家的 IDE”里解放出来。我用 vscode 写了三年 Fiori，最直接的体感是三点：第一，本地启动速度快，项目几十个源文件，npm start起来也就是两三秒的事，不用等云端冷启动。第二，编辑器本身的体验好，代码高亮、自动补全、Git 集成、终端管理都是现代前端工具的标配，写 SAPUI5 的 XML 视图和 controller 里那段 JavaScript 时爽快很多。第三，插件生态自由，VSCode 里既能装 SAP Fiori Tools，也能装 GitLens、Prettier、ESLint 这些通用前端工具，一个编辑器把 Fiori 和其他技术栈的开发工作全包了。

1.3 这套方案适合什么样的人

如果你是从传统 ABAP 或者 Web IDE 刚转过来的，VSCode 这套需要一些前端工具链的基础，比如 Node.js、npm、代理这些概念，并不是零门槛。但如果你已经对 VSCode 很熟，只是想把 Fiori 开发也并入这个工作流，那恭喜你，门槛比想象中低很多。适合个人开发者、本地学习 Fiori 的新人，也适合那些想摆脱浏览器 IDE 卡顿、想让日常编码更趁手的团队。

2. 环境准备与工具链搭建

2.1 Node.js 与 Java JDK 的版本选择

Fiori 开发在本地跑起来全靠 Node.js 撑着，Node 版本是第一个坑。SAP Fiori Tools 官方要求 Node.js LTS 版本，我自己长期用的是 Node.js 18 LTS，跑 Fiori Tools 5.x 和 UI5 1.100+ 都没问题。如果你电脑上版本偏低，比如 Node 12 或者更老，fiori 相关的命令会直接报错，或者装了扩展也启动不了服务。建议装一个 nvm（Node Version Manager），随时切换 Node 版本，避免项目多了之后版本打架。

Java 这块很多教程没提，但如果你要用 Fiori Tools 里的 XML Preview、Annotation 生成这些功能，本机得有 JDK 环境，建议装 OpenJDK 8 或 11。我的经验是 JDK 11 稳定性最好。验证方法很简单，终端里跑一下java -version，能正常输出版本号就说明没问题。

2.2 扩展安装与推荐清单

先打开 vscode 的扩展面板，搜索“SAP Fiori Tools”，安装SAP Fiori Tools - Extension Pack这个官方扩展包。它会把 Application Modeler、Service Modeler、XML Preview、脚手架生成器这些子扩展一并装好，省得一个个找。装完之后右下角如果提示重新加载窗口，就重载一次。

除了官方扩展包，我还推荐装这几个搭配使用的插件：SAP UI5 Language Assistant能在写 XML 视图的时候给出控件和属性的补全提示；UI5 Inspector（这是 Chrome 的调试工具，但跟流程强相关）配合使用效果很好；再有就是前端工程化常用的ESLint和Prettier，保持代码风格一致。要提醒的是建议把Auto Rename Tag、Path Intellisense这类日常写代码的小工具也装上，编辑 XML 视图的时候体验会明显提升。

2.3 验证环境是否就绪

装完扩展之后，先别急着建项目，打开命令行（VSCode 里的 Ctrl+` 调出终端也行）挨个执行下面几条命令，确认这三样核心工具都在：

node -v npm -v java -version

再确认扩展没有报错。有一个小技巧：在 vscode 里按Ctrl+Shift+P，输入“Fiori”，如果命令面板里能看到Fiori: Application、Fiori: Open Application、Fiori: Generate Preview这几项，说明扩展加载成功了。如果只有一两个命令，大概率是扩展没装完整，或者 Node 路径没有被 vscode 识别到，重启一下 vscode 再试。

3. 从零搭建一个 Fiori 项目

3.1 用 Fiori Tools 的向导快速搭框架

确认环境没问题后，建项目最省事的方式就是用 Fiori Tools 自带的 Application Generator。操作路径：按Ctrl+Shift+P打开命令面板，输入Fiori: Application，回车，向导就会出来。

向导会问你几个关键信息：第一，数据源类型，是直连后端系统，还是先用临时测试数据，或者使用一个 OData 服务 URL。我建议新手先用临时数据走通流程，后面再对接真实后端。第二，模板选型，常用的有 Basic Template（最简单的单页面）、List Report（列表+详情页）、Worklist（工作列表）等。如果你是第一次跑通全流程，别犹豫，选 Basic Template。第三，填写项目名称和命名空间，比如项目名training，命名空间my.fiori，生成出来的应用 id 就是my.fiori.training。

点击生成后会有一小段时间自动执行依赖安装。如果卡住不动，检查一下网络，npm install 偶尔会被网络问题卡死。整个过程顺利的话，左侧会看到一个标准的项目结构：webapp文件夹下面是源码，根目录有package.json、ui5.yaml、ui5-local.yaml等文件。

3.2 理解工程结构：webapp、ui5.yaml 与 package.json

拿到项目第一步，先把结构看清楚，后面出问题才知道去哪里找根源。

webapp是前端源码目录，主要看三个文件：manifest.json里注册了应用的路由、模型、组件信息；Component.js是应用的启动入口；view/目录下放 XML 视图，controller/目录下放对应的控制器代码。

ui5.yaml是 UI5 构建工具的配置文件，里面声明了框架名称、UI5 版本、依赖库，以及服务器的中间件扩展。一个典型的基础配置长这样：

specVersion: "3.0" metadata: name: my.fiori.training type: application framework: name: SAPUI5 version: "1.120.0" libraries: - name: sap.m - name: sap.ui.core server: customMiddleware: - name: fiori-tools-proxy afterMiddleware: compression configuration: ignoreCertError: false backend: - path: /sap url: https://sapserver.example.com destination: my_backend

package.json声明了依赖和启动脚本，最核心的两个命令是npm start（启动本地开发服务器）和npm run build（执行 UI5 构建），后面操作都会用到。

3.3 连接后端 OData 服务的两种常见配置

开发真实 Fiori 应用时最常做的事，就是把本地代码和后端的 OData 服务连通。Fiori Tools 在这块封装了一层代理，原理是本地启动的开发服务器会在中间做转发，把前端发起的/sap/...请求转发到真实后端。

配置方式是在ui5.yaml的backend段里加上后端地址。如果你有 ABAP 后端，通常这样配：

server: customMiddleware: - name: fiori-tools-proxy afterMiddleware: compression configuration: backend: - path: /sap url: https://your-abap-server.example.com:443 client: '100'

如果你用的是 SAP BTP 上的服务，那就不能直接写地址了，得配一个destination名称，本地通过 BTP 的 Cloud Connector 间接访问。这种场景下url字段可以留空或者填目标系统地址，关键是给destination指定 BTP 上的目标服务名。

我在实际项目中通常开两个后端配置：一个开发环境（dev），一个测试环境（test），改一下url和destination就能切换数据源，很方便，但注意别把真实后端地址提交到公开的代码仓库里。

3.4 手动创建 OpenUI5 项目的备选方案

有时候不想用官方那套扩展，或者需要纯开源技术栈的组合，也可以手动搭一个 OpenUI5 项目。核心是写一个package.json，然后通过@ui5/cli来管理生命周期。最简单的最小版本：

{ "name": "my-openui5-app", "version": "0.0.1", "scripts": { "start": "ui5 serve", "build": "ui5 build --all" }, "devDependencies": { "@ui5/cli": "^3.0.0" } }

加上ui5.yaml：

specVersion: "3.0" metadata: name: my-openui5-app type: application framework: name: OpenUI5 version: "1.120.0" libraries: - name: sap.m - name: sap.ui.core

然后执行npm install和npm start，浏览器打开提示的端口就能看到一个空的应用。这个方案的好处是干净、不受厂商工具绑定，坏处是没有官方脚手架那套图形化配置，数据源、代理这些都得手写配置。适合已经有一定基础的人。

4. 本地运行、调试与预览

4.1 启动本地开发服务器

项目建好后，终端执行npm start，控制台会输出本地访问地址，通常默认是http://localhost:8080或者 Fiori Tools 分配的随机端口。浏览器打开就能看到应用根页面。开发服务器做了热更新，改完 JavaScript 或 XML 保存后刷新页面即可，不需要重启服务。

如果执行npm start后提示找不到fiori命令，多半是依赖没装全，删掉node_modules重新npm install一次就好。如果端口被别的进程占用，终端会很明确地提示端口冲突，换一个端口启动即可。

4.2 VSCode 断点调试控制器代码

Fiori 应用的逻辑主要在 controller 的 JavaScript 代码里，本地起服务后，VSCode 可以直接下断点调试。方法很简单，在.vscode/launch.json里写一个 Chrome 调试配置：

{ "version": "0.2.0", "configurations": [ { "type": "pwa-chrome", "request": "launch", "name": "Fiori Debug", "url": "http://localhost:8080", "webRoot": "${workspaceFolder}/webapp" } ] }

然后先跑npm start，再按F5，VSCode 会自动打开 Chrome 并定位到应用页面，在 controller 的 JavaScript 代码里点行号打断点，页面加载到那一行就会停下来。这个比在浏览器里靠console.log一点一点猜要高效得多。

4.3 XML 视图预览与代码补全

写 XML 视图时，SAP Fiori Tools 提供了一个很实用的功能：Fiori: Generate Preview。执行后会生成一个预览页面，把当前的 XML 视图渲染出来，不用启动整个应用就能看到 UI 效果。这对调布局、核对控件属性特别有用。

同时SAP UI5 Language Assistant插件会在你输入 XML 标签时给出控件补全。比如输入<m会提示sap.m里的Button、Input、Panel等控件，选中后自动补全标签并带上必填属性。

4.4 用 fiori-tools-proxy 解决跨域与认证问题

前端应用直接请求后端 OData 服务时，最常碰到的问题就是跨域（CORS）。解决思路不是让后端改跨域策略，而是在本地开发环境中使用 Fiori Tools 自带的代理组件：所有请求都发给本地服务，由本地服务再转发给真实后端，浏览器看到的永远是同源请求，跨域自然就不存在了。

配置上就是前面讲到的ui5.yaml里的backend段。还有一个额外参数ignoreCertError: true值得注意。很多企业后端用的是自签名证书，默认情况下代理会拦截证书错误，导致请求失败；把ignoreCertError设为true能跳过去，仅限本地开发环境这么做，生产环境绝对不能开。

5. 常见问题与排查技巧

5.1 命令面板里找不到 Fiori 命令

这个问题出现频率极高，原因也简单：Fiori Tools 扩展只会在工作区打开正确结构的项目之后才会激活命令。如果你在某个空文件夹上按Ctrl+Shift+P，看不到 Fiori 命令是正常的。解决办法是先打开项目的根目录，确认webapp文件夹存在且里面有manifest.json，再重载窗口，命令面板就能搜到了。

5.2 Node 版本不对导致的各种诡异报错

Fiori 开发中很多莫名其妙的报错，最后都指向 Node 版本太旧或太新。比如fiori run命令找不到、依赖安装后启动服务器报语法错误、脚手架生成中途退出等等。我的排查套路是先把 Node 切到 LTS 版本。用 nvm 的话一行命令就能解决：

nvm install 18 nvm use 18

然后再重跑npm install。如果项目里锁定了特定 Node 版本，也可以在package.json的engines字段里声明，减少团队协作时的坑。

5.3 本地服务能启动，但 OData 请求全部失败

先确认请求是走代理而不是直连的。浏览器开发者工具里看网络请求的 URL，如果是http://localhost:8080/sap/...，说明代理配置没问题；如果直接请求的是后端域名，说明ui5.yaml里的backend配置没生效，检查路径是否被注释或者格式写错了。其次确认证书参数，多数后端自签名证书场景下把ignoreCertError: true加上。最后还要看一眼后端地址是否可达，从本地终端直接ping不通的情况下，代理配置写得再对也是空转。

5.4 从 WebIDE/BAS 迁移到 VSCode 的几点差异

WebIDE 和 BAS 里的很多功能是云端封装好的，比如一键部署、注解生成、团队协作空间。迁移到 VSCode 后这些能力需要手动配。部署这块，Fiori Tools 提供了Fiori: Deploy命令来对接 BTP Cloud Foundry，但需要提前在本地安装 Cloud Foundry CLI 并登录。如果你做的是 ABAP 环境部署，则要通过npm安装@sap/ux-ui5-tooling相关组件，流程稍微繁琐一点，习惯之后也不复杂。

还有一个容易被忽略的差异：BAS 的项目默认帮你做了很多代码规范化配置，VSCode 项目里这些需要自己引入。建议从第一天就配好 ESLint 和 Prettier，避免代码风格失控。

5.5 构建与部署的注意事项

团队开发中经常需要输出用于测试环境的构建包，命令是npm run build，生成结果在dist目录。这里有个容易踩的坑：构建之后出现资源 404 或者样式错乱，大多是因为运行时用了相对路径或者路径前缀配置问题，需要对manifest.json和ui5.yaml里的路径配置做检查。部署到测试环境后，如果页面白屏，先看控制台有没有资源加载失败的报错，再回溯构建时的路径配置。

部署到 BTP 时，打包成 MTAR 要用到mbt工具，顺手也验证一下本地是否安装：

mbt --version

没有的话全局安装@sap/mbt即可。部署命令Fiori: Deploy会要求选择目标组织、空间和 destination，这些信息提前在 BTP Cockpit 里准备好。

最后分享几个我反复踩坑后形成的个人习惯。第一，升级任何核心依赖（Node、Fiori Tools、UI5 版本）之前，先备份一份能跑通的项目副本，升级完跑不通还能回滚。第二，本地开发时给ui5.yaml加好ignoreCertError: true，但部署配置里务必去掉，这个参数在生产环境是安全隐患。第三，写 controller 逻辑时尽量用 VSCode 的断点调试，别全靠浏览器 console，排查问题的效率完全是两个量级。VSCode + Fiori 这套组合，熟悉之后会明显感觉开发速度比在浏览器 IDE 里快不少，值得花一个下午把环境彻底搭好。