企业官网建设流程全解析

最近一直在折腾 SAP Fiori，这应该是很多 SAP 从业者绕不开的一条路。从 SAPUI5 到 Fiori Elements，整个技术栈都是基于前端生态的，入门第一步就是把 VSCode 开发环境搭好，然后跑通一个最简单的 helloworld。这个流程看起来简单，但真正动手时，Node.js 版本、npm 镜像、脚手架工具、Fiori tools 插件的兼容性会在头一两个小时里轮番考验你。所以我干脆把整个过程重新整理了一遍，从选型思路到每一步操作、我踩过的坑以及排查方法都写清楚，希望能帮你少走点弯路。

这套内容适合刚接触 SAP Fiori、想在自己的电脑上把本地开发环境配置好的朋友，也适合之前用 Web IDE 或 Business Application Studio 但想转到 VSCode 的开发者。不需要你有很深的 UI5 基础，但最好对 HTML、JavaScript 有一点概念，知道 npm 是什么，不然在后面装依赖的时候会比较懵。

1. 为什么是 SAP Fiori + VSCode：环境选型背后的考量

1.1 SAP Fiori 是什么，HelloWorld 为什么值得先做

SAP Fiori 是 SAP 推出的一套用户体验设计规范，同时在实际开发中通常也指代基于 SAPUI5 或开源版 OpenUI5 来构建 Web 应用的这套技术栈。它强调角色驱动、响应式、简单直观，所以你在 SAP S/4HANA 里看到的很多界面，尤其是 Fiori Launchpad 里面的那些应用，本质上都是跑在 SAPUI5 框架之上的页面。

很多新手的第一步是去记 SAPUI5 的生命周期方法、看各种控件的 API，但我更建议先做一件事：把本地环境跑通，生成一个能在浏览器里打开的页面。为什么？因为 SAP Fiori 开发链路上有很多隐藏依赖，Node.js、npm、UI5 CLI、Git、脚手架工具，任何一个环节出问题，后面的代码再对也跑不出来。先跑通一个 helloworld，就是在小范围内把所有变量都消掉，确认环境是好的，再往上叠加复杂度才有效率。这也是我当初踩了很多坑之后养成的习惯，不管学什么框架，第一天先别学语法，把“空项目能在本地跑起来”当成唯一目标。

1.2 开发环境的主流选择与 VSCode 的优势

SAP 官方提供的开发环境有好几种。最早的 SAP Web IDE，是基于浏览器的开发工具，早期用的人很多，但现在已经逐渐被 SAP Business Application Studio（简称 BAS）取代。BAS 是云端的，好处是免配置、预装了很多 SAP 相关的插件，坏处是网络不好的时候体验很折磨，而且免费额度用完之后要花钱。

VSCode 是另一条完全不同的路。它本质上是一个轻量编辑器，但通过插件生态几乎可以替代一切。对 SAP Fiori 开发来说，微软和 SAP 官方都维护了相关插件，比如 SAP Fiori tools，可以直接在 VSCode 里生成项目、预览应用、调试代码。再加上 VSCode 启动速度快、内存占用比全家桶低、Git 集成好用，说实话，在本地做 UI5 学习和项目开发，VSCode 是比 BAS 更顺手的选择。

另外还有一个很现实的原因：VSCode 是通用编辑器。你今天学 SAP Fiori，明天可能还要写 Python、C++、STM32 或者 Vue3，一套编辑器全搞定。网络上有大量 VSCode 配置教程，包括设置中文、配置 Python 环境、配置 C/C++ 环境等等，生态足够丰富，遇到问题一搜就能找到答案。所以我始终认为，学 SAP Fiori 的第一站不应该是某个云端 IDE，而是先把 VSCode 这套本地开发环境摸熟。

2. 搭建前的准备：工具清单与核心概念

2.1 需要准备哪些东西

在动手之前，先把要装的东西列个清单，避免做到一半才想起来缺东西：

• VSCode：主力编辑器，装最新稳定版就行。
• Node.js：必须安装，最好选 LTS 版本，UI5 工具链是跑在 Node.js 上的。
• Git：必须安装，脚手架工具在生成项目时依赖 Git 来初始化仓库。
• 浏览器：推荐 Chrome 或 Edge，Fiori 应用调试时用开发者工具比较方便。
• SAP Fiori tools 插件：VSCode 扩展市场里搜 SAP Fiori tools，装它。
• Yeoman 和 easy-ui5 生成器：用来生成 UI5 项目脚手架，后面细说。

这里面最容易忽略的是 Git。很多新手只装了 Node.js 就跑去运行生成器，结果报错找不到 git，然后一脸懵。Yeoman 生成项目的时候会在最后一步自动执行 git init，如果没有 Git，整个过程直接中断。所以提前把 Git 装好，而且确保git --version在命令行里能正常输出版本号。

macOS 用户如果之前装过 Xcode Command Line Tools，系统会自带 Git，但保险起见还是自己装一个最新版。Windows 用户建议一直点默认选项，注意在安装过程中选择“从命令行使用 Git”而不是“仅从 Git Bash 使用”，这样在 VSCode 的终端里才能直接调用 git。

2.2 SAP Fiori 开发环境的关键概念

如果你完全没接触过 UI5，先别急着看代码，先搞清楚几个名词，不然看教程会像看天书。

SAPUI5 和 OpenUI5：SAPUI5 是 SAP 的商业版前端框架，功能更全，需要连接 SAP 后端才能发挥全部威力。OpenUI5 是同一个框架的开源版本，代码结构几乎一样，但缺少部分企业级控件，本地学习完全够用。用 easy-ui5 脚手架生成的项目默认用的就是 OpenUI5，这没问题，因为 HelloWorld 不需要任何 SAP 后端资源。

Node.js 和 npm：Node.js 让 JavaScript 可以在本地运行，npm 是它的包管理器，用来下载各种工具库。VSCode 里的前端开发，本质上就是在 Node 环境下用 npm 安装依赖、运行脚本。

UI5 CLI：UI5 的命令行工具，负责本地启一个 HTTP 服务来跑项目。你可以把它理解成 UI5 版的 dev server，这样在浏览器里访问 localhost 就能看到页面，而不是傻傻地双击 index.html 用 file 协议打开。

脚手架工具：Yeoman 是一个项目生成器框架，easy-ui5 是专门生成 UI5 项目的模板。它的作用就是帮你把 index.html、manifest.json、Component.js 这些基础文件一次性生成好，不用手写一堆样板代码。

Fiori Elements 和自由式 UI5：Fiori Elements 是基于 OData 服务的配置化开发模式，写少量 JSON 配置就能生成 CRUD 应用，适合标准场景。自由式 UI5 则是完全手写 View 和 controller，灵活但是代码量大。HelloWorld 阶段用自由式就够了，理解 MVC 结构更重要。

3. 从零开始：VSCode 开发环境详细安装与配置

3.1 安装 VSCode、Node.js 与 Git

先说 VSCode。去官网下载对应系统的安装包，Windows 下安装的时候建议把“添加到 PATH”和“在右键菜单中打开”这两个选项选上。很多人装完之后在终端里敲code没反应，就是因为 PATH 没配好。装好后打开 VSCode，按Ctrl+Shift+P输入language可以看到配置显示语言的选项，现在先不管，一会装中文插件。

接下来装 Node.js。记住一个原则：不要追新，坚决选 LTS 长期支持版。因为 UI5 工具链对最新的 Node 主版本并不总是第一时间适配，选 LTS 最稳。装完后打开终端，分别输入node -v和npm -v，能看到版本号就说明这一步完成了。如果你之前装过老版本 Node，建议先卸载干净再装 LTS，不然版本混乱会引发一堆奇怪问题。

然后是 Git。Windows 用户装完后建议把默认编辑器改成 VSCode，在安装界面的 Select Default Editor 那里选择 “Use Visual Studio Code as Git's default editor”，这样 Git 操作遇到冲突时会直接调用 VSCode 解决，体验好很多。装好后在终端输入git --version，看到版本号就说明没问题。

这里要特别强调：在继续往下走之前，最好把 VSCode、Node.js、Git 这三个东西都装完再开始，不要装完一个就跑脚手架。因为 easy-ui5 生成器在生成项目时全会检查，少一个就会中途报错，到时候你分不清是哪儿的问题。

3.2 VSCode 关键插件推荐与配置

VSCode 最值钱的不是编辑器本身，而是插件生态。做 SAP Fiori 开发，有几个插件我是强烈建议装的：

第一个是中文语言包，插件名叫 Chinese (Simplified) (简体中文) Language Pack。装完按Ctrl+Shift+P，输入Configure Display Language，选择zh-cn，然后重启 VSCode 就是中文界面了。不仅看着舒服，搜索设置项的时候也更容易看懂。

第二个是 SAP Fiori tools，这个是官方插件。它提供了一批子插件，包括项目模板生成、Fiori 预览、YAML 编辑等。装完之后侧边栏会出现 SAP Fiori 相关的图标，点击可以快速创建 Fiori 应用。它和 easy-ui5 脚手架是两条平行的路线，后面我会对比讲。

第三个是 ESLint 和 Prettier。UI5 社区有自己推荐的代码规范，ESLint 帮你检查语法问题，Prettier 帮你格式化代码。装完在设置里开启editor.formatOnSave，保存代码时自动格式化。具体配置可以在项目根目录创建.prettierrc，我一般用下面这组：

{ "semi": true, "singleQuote": true, "printWidth": 100, "tabWidth": 2 }

还有一个我强烈建议装的：GitLens。它能在代码行上显示这一行最后是谁、在哪个提交里改的，对多人协作非常有价值。虽说是 IDE 自带的 Git 已经够用，但 GitLens 的体验明显更好。

插件装完，我还会做两件小事。一是设置终端默认 shell，Windows 用户把默认终端从 PowerShell 改成 Command Prompt，或者反过来，看你自己习惯，关键是要统一，避免教程里敲的命令在某种终端里不支持。二是创建一个用户代码片段，方便以后快速生成一个最小 UI5 View。在 VSCode 里打开命令面板，输入Snippets: Configure User Snippets，选择New Global Snippets file，叫ui5-snippets，然后塞进去：

{ "UI5 XML View": { "prefix": "ui5-view", "body": [ "<mvc:View xmlns:mvc=\"sap.ui.core.mvc\" xmlns=\"sap.m\">", " <Text text=\"${1:Hello World}\" />", "</mvc:View>" ], "description": "Create a minimal UI5 XML view" } }

之后在 XML 文件里输入ui5-view再按 Tab，就能直接生成一个基础视图，省去手打命名空间的麻烦。

3.3 验证开发环境是否就绪

不要急着生成项目，先做一轮环境自检。打开 VSCode 终端，依次敲这几个命令：

node -v npm -v git --version

如果都正常，再装 UI5 CLI 和 Yeoman 生成器。

npm install -g @ui5/cli npm install -g yo generator-easy-ui5

这一步可能会比较慢，如果发现 npm 一直卡住或者报网络错误，大概率是网络问题。国内环境下我建议先把 npm 镜像源切到国内镜像，执行：

npm config set registry https://registry.npmmirror.com

然后再重新执行安装命令。装完之后分别确认一下版本：

ui5 --version yo --version

yo --version能输出版本号，说明 Yeoman 可用。如果执行yo时报错说找不到命令，在 Windows 上是 PATH 没生效，重启 VSCode 试试，还不行就把 npm 的全局目录加到系统 PATH 里。做完这些，开发环境算是基本就绪了，可以进入真正的 HelloWorld 环节。

4. 实践第一个 SAP Fiori 应用：HelloWorld 的完整实现

4.1 使用 easy-ui5 脚手架初始化项目

首先在 VSCode 里打开一个新文件夹，比如D:\fiori-learning。然后在终端执行：

yo easy-ui5

Yeoman 会进入交互式问答，有几个关键选项需要注意：

• What is your application name?-> 输入helloworld
• What is the namespace for your application?-> 输入com.sample
• Which UI5 framework do you want to use?-> 选OpenUI5
• Which UI5 version do you want to use?-> 保持默认 LTS 版本
• Which view type do you want to use?-> 选XML
• Where should I create the project?-> 选当前文件夹

这里有一个常见的坑：应用名称和命名空间不要用中划线以外的特殊字符，更不要出现空格。命名空间加应用名的组合最终会变成包名，比如com.sample.helloworld，如果中间有非法字符，加载资源的时候会直接 404。另外一个建议是应用名保持小写，虽然技术上允许大小写混合，但 URI 大小写敏感，后面访问资源时会因为记错大小写而来回折腾。

生成过程最后会执行 npm install 和 git init，耐心等它跑完。如果看到类似Your project is ready的提示，说明项目结构已经生成成功。这时候 LT 终端里可能还有npm audit的输出，不用管它，那是依赖安全的提示，不影响项目运行。

4.2 理解 UI5 项目结构

很多人拿到项目后第一时间去找那个写着 Hello World 的页面，但看半天不知道哪里改。先静下心来看结构。easy-ui5 生成的项目大概是这样的：

helloworld/ ├── webapp/ │ ├── controller/ │ │ └── App.controller.js │ ├── view/ │ │ └── App.view.xml │ ├── index.html │ ├── manifest.json │ ├── Component.js │ └── ... ├── package.json └── ui5.yaml

真正要关注的是 webapp 目录。index.html是应用入口，浏览器最先加载它；manifest.json是应用的配置文件，描述应用 ID、依赖库、路由等信息；Component.js是组件入口；view/App.view.xml是界面定义，XML 文件里写哪些控件，页面上就显示什么；controller/App.controller.js是控制器，负责响应界面事件。

你不需要背这些文件的作用，但至少要形成一种感觉：UI5 应用把界面和逻辑分开了。View 里写界面长什么样，Controller 里写点击按钮之后干什么。这种 MVC 结构在 SAP Fiori 项目里是通用的，今天在 HelloWorld 里见到的这几个文件，在大型项目里依然会见到，只是文件和目录会更多。

xui5.yaml是 UI5 工具链的配置，package.json是 npm 脚本配置。如果你看到根目录有这两个文件，说明项目是标准的 UI5 工具链项目，后面启动服务就看这里的脚本。

4.3 编写并运行 HelloWorld

接下来改代码。打开webapp/view/App.view.xml，正常情况下里面已经有内容了，可能是：

<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m"> <App> <Page title="Hello World"> <Text text="Hello World" /> </Page> </App> </mvc:View>

如果没有，就把上面内容覆盖进去。然后启动本地服务，在终端执行：

npm start

这个命令底层调用的是 UI5 CLI，默认会启动一个本地开发服务器，端口通常是 8080。看到终端输出Server started之后，浏览器访问：

http://localhost:8080/index.html

如果一个写着 Hello World 的页面出来了，恭喜你，环境已经彻底通了。到这里，SAP Fiori 的第一个应用已经成功跑起来。

想让它更有意思一点，可以做两个改动。第一个，把 Text 的显示内容改成中文“你好，SAP Fiori”，保存后浏览器自动刷新就能看到。第二个，给 Page 加一个图标背景，让它看起来更像一个正经应用。不过要注意，如果项目里没有现成的 SAP 图标资源，OpenUI5 在编译时会尝试从 CDN 加载，断网环境下图标就显示不出来，这点不追求的话可以先不放。

再说一个我当初困惑了很久的点：为什么在终端敲npm start能启动而不是敲ui5 serve？看package.json里的scripts就明白了。easy-ui5 生成的项目里通常定义了start、serve、build这几个脚本，start等价于ui5 serve -o index.html，也就是启动服务并自动打开浏览器。理解了脚本定义，后面想调整端口就自己改package.json或ui5.yaml就行，不用到处找配置入口。

4.4 用 SAP Fiori tools 扩展的方式做对比

用 easy-ui5 脚手架是一种方式，官方更推荐的方式是直接用 VSCode 里的 SAP Fiori tools 插件。这个插件装好后，在命令面板里输入Fiori: Open Application Generator，会弹出图形化向导。你需要选择模板类型，HelloWorld 这种简单页面选 Basic Template 就行，然后填应用名称、命名空间、UI5 版本等参数，最后选“生成到本地文件夹”，插件会帮你生成一套类似的 UI5 项目。

这两种方式怎么选？我的体会是：easy-ui5 更适合学习，流程透明，每一步在做什么都能看到，而且生成的代码结构比较干净。SAP Fiori tools 更适合后续连接 SAP 后端，尤其是你想创建 Fiori Elements 应用时，向导里会要求配置 OData 服务，这是 easy-ui5 不具备的。我的建议是第一个项目别用官方插件，老老实实用 easy-ui5，先搞明白结构，等你理解了之后再切回官方工具，会顺畅得多。

5. 实操中常见问题与排查技巧

5.1 常见报错与解决方案速查表

从装环境到跑起 HelloWorld，我把最常见的几个报错整理成了表格，推荐你把它存下来当速查手册用。

关于端口占用，我再展开说一下。在终端执行：

netstat -ano | findstr :8080

找到占用端口的 PID，然后在任务管理器里结束对应进程就可以。如果这是某个重要服务，那就不要强杀，直接改端口更稳妥。UI5 项目改端口有两种方式，临时方案是在启动命令里加参数：

ui5 serve -p 8081

永久方案是在ui5.yaml里的 server 配置下加port: 8081。第一次做端口配置时建议用命令参数，简单直接，不影响项目文件。

还有一个非常容易被忽视的坑：项目路径不能有中文。如果你的项目文件夹放在桌面\新建文件夹这种含中文的路径下，UI5 工具在解析路径时可能会报编码错误，而且是那种不太容易看懂的报错。我把 Fiori 项目统一放在D:\dev目录下，全英文路径，一次问题都没出过。

5.2 一些值得注意的经验

最后分享几条我在实际使用中总结出的经验，这些不是文档里会写的，但真的很管用。

第一，学这门技术的第一步永远是先跑通最小闭环。我见过太多人还在研究 SAP Fiori 的理论模型，结果连本地服务都不会起。如果你能三分钟把 HelloWorld 跑起来，后面学路由、学数据绑定的时候至少敢动手试错，而不会因为环境问题劝退。

第二，命令行输出要认真看，但别被吓到。npm 安装的时候会刷一大屏警告，很多是无关紧要的。真正要关注的是error开头的报错，以及你刚执行的那条命令最终有没有成功。学会抓关键信息，能省不少时间。

第三，VSCode 的调试功能对 UI5 很友好。不要只停留在运行项目的层面，试试在App.controller.js里打个断点，然后按 F5 启动调试。VSCode 会自动绑定 Chrome 调试端口，你能在编辑器里直接看到变量的值。我在排查 UI5 事件绑定问题的时候，基本都是靠断点而不是打日志。

第四，数据绑定才是 Fiori 的核心。HelloWorld 里只有一个静态 Text 控件，真正到业务场景中，你需要在 View 里用{/modelProperty}这种语法绑定 JSON 模型，在 Controller 里创建模型、赋值、更新。建议你在 HelloWorld 跑通之后，立刻尝试给 Text 绑定一个模型属性，然后把控制器里的值改掉看看页面的反应。这一步做完，才算真正开始理解 Fiori 的数据流。

还有一个体会：SAP Fiori 的学习曲线并没有想象中陡峭，难点在于概念多、依赖多。用 VSCode 作为开发环境的好处是，整个工具链都是现代前端标配，你在网上搜 UI5 问题的时候，经常会顺便看到 Vue、React 项目的解决方案，原理相通，参考价值很高。所以别怕，按部就班把环境配好，跑起第一个 helloworld，后面每一步都会越走越顺。

我在实际使用中，最后特别爱做一件事：给 VSCode 配好一套自己的快捷键和工作区设置，比如侧边栏位置、缩进、主题、代码片段，然后把这些偏好写成一份settings.json放到团队共享的配置里。这种做法能显著降低日常开发的心智负担。总之，先把环境搭明白，你的 SAP Fiori 之旅才算真正开始。