Delphi转Web：三套框架选型与踩坑指南

简介这套基于TMS WEB Core框架的Delphi Web前端教程面向Delphi与Lazarus开发者、Web前端初学者及进阶人员帮助读者用熟悉的Pascal语言跨入跨平台Web应用开发降低从桌面程序转向浏览器端与移动端的学习门槛。压缩包内只有1个PDF文件大小约3.84MB结构紧凑适合在电脑或平板上集中阅读既可顺序通读也方便围绕具体组件与部署问题定位章节。内容从框架配置、项目设置、编译流程、运行时库讲到页面设计、组件使用、调试与部署并比较几款主流Web框架的特点目录还覆盖渐进式网页应用、桌面应用及自动化版本管理等主题便于读者按模块理解纯网页应用的完整开发流程。已有5029人学习适合希望把Delphi技能延伸到Web、移动与桌面场景的开发者系统入门、对照实践、逐步排查、巩固和查漏补缺。1. Delphi 老手转 Web我为什么把三套框架都装上跑了一遍「Delphi Web前端」这件事很多同行的第一反应是前端不是 JavaScript 框架的地盘吗我原本也这么想直到把一套内部管理系统前端用 TMS WEB Core 重写了一遍——代码量比原来的 JS 版少了将近一半动手的人是个十年没写过 JavaScript 的 Object Pascal 老手两周就摸熟了。反直觉的点在于这并不表示「用 Delphi 写后端再套个壳」Pas2JS 编译出来的是真正的 HTML/JS 产物服务端只要一个能托管静态文件的目录就行。为了确认这条路不是单点特例我把 IntraWEB、uniGUI、TMS WEB Core 三套框架各装一遍、各跑同一个需求把判断依据、产物差别和配置阶段最容易翻车的点都记了下来。这份基于 TMS WEB Core 框架的教程 PDF正好补上了我缺的那块系统性内容下面按我实际比过的方式讲。2. 三套框架的定位差谁在服务端渲染谁在浏览器里跑选型最容易犯的错是拿功能列表对齐着比。三套框架的组件数、控件名、Demo 长得都挺像但它们的运行时边界完全不同而这条边界决定了后面所有的成本托管方式、并发模型、调试手段、甚至你在哪儿看错误日志。我一般会先问一句「这段按钮点击的代码最终跑在谁的进程里」答案一出来剩下的对比就只是细节了。2.1 运行时边界一行点击事件到底在哪儿执行IntraWEB 的思路是把 Delphi 的窗体模型搬到 Web 上但它保留了服务端的存在感页面结构由服务端参与生成交互事件通过回发机制回到服务端处理处理完再把变化推回浏览器。这条链路的好处是——你写的 Pascal 代码几乎全在服务端跑数据库连接、文件访问、业务对象全是你熟悉的那一套脑子里不用切换到「浏览器沙箱」。uniGUI 也走服务端会话驱动这条路态度更彻底一些每个浏览器连接在服务端对应一个会话窗体、控件状态都挂在会话里用户操作触发的是服务端事件。写过传统 VCL 桌面程序的人上手会非常顺因为思维模型没变只是「屏幕」换成了浏览器。TMS WEB Core 反过来它把逻辑整个搬到浏览器里执行。你在 Delphi IDE 里写的 Pascal经 Pas2JS 编译成 JavaScript和 HTML、CSS 一起打包浏览器加载后本地执行。服务端不再参与每一帧的运算它退化成一个静态文件服务器或者一个提供 REST 接口的后端。这个差别在实际项目里非常要命。我在一个多人在线填报的场景里试过服务端会话方案几十个人同时操作时服务端会话对象的内存占用和连接保持成本是实打实要算的扩容基本等于加进程、加会话管理。换到浏览器执行的模型并发压力直接转嫁给用户自己的机器和静态托管服务端只剩接口调用扩容思路立刻变成「接口限流 静态资源上 CDN」这种熟悉的前端逻辑。2.2 TMS WEB Core 的产物形态100% HTML/JS 意味着什么教程里对这一点写得很直白它是能生成真正 100% Web HTML/JS 应用的 Delphi 框架产物里没有二进制文件、没有可执行文件生成的 Web 应用可以直接部署到任何托管服务器。这句话听起来像宣传语但拆开看是三个具体的工程结论。第一部署变成了纯文件拷贝。你不需要在目标机上装运行时、注册服务、配 IIS 应用程序池或者 systemd 单元把编译输出目录整个扔到静态托管根目录就完事。我在一个客户内网就是这么干的运维同事只做了一件事把目录拷进已有的静态站点。没有额外的进程要守护也没有端口要开。第二版本回滚变得极其便宜。前端产物是一堆静态文件出问题把上一版目录改个名就回去了不用处理「服务停了一半」这种中间态。这一点在我踩过一次发布事故之后体会特别深——那次是接口字段改名导致列表页全白回滚只花了十几秒。第三你要接受一个新现实业务逻辑跑在用户机器上任何写在前端的判断都不可信。菜单权限、按钮显隐、字段校验,这些在桌面程序里可以放心写在客户端的东西在这里必须由后端接口再校验一遍。这不是 TMS WEB Core 的缺陷是 Web 前端的通性但传统 Delphi 程序员最容易在这里翻车。2.3 IntraWEB 与 uniGUI 更适合谁把话说得功利一点如果你手上的系统是重表单、重业务规则、用户数可控几十到几百、部署环境是内网服务器那么服务端会话方案能让你用最短路径把一套桌面程序搬上浏览器。逻辑不用重写数据访问不用改成 REST团队里没人需要懂 JavaScript。这类需求用 TMS WEB Core 当然也能做但你要多做一层接口还要处理跨域和鉴权性价比不一定高。反过来如果你的目标里有这几条中的任意一条——要部署到公网、要面对不确定的并发量、要做 PWA 或桌面壳应用、要让页面能被正常索引和分享、团队里已经有 REST 后端——那浏览器执行的模型优势就很明显。教程里提到的四种项目形态Web 应用、渐进式 Web 应用、Electron 桌面应用、Miletus 桌面应用本质上是同一份 Pascal 代码配不同的壳这个复用度是服务端方案给不了的。我不建议把这三套当成「谁替代谁」来理解。它们解决的是同一个问题的不同切面选错的成本主要不在开发期而在上线后的运维和扩容上。3. 选型四个维度渲染方式、产物形态、组件生态、调试链路功能列表对齐着比没有意义因为三家的控件都能拼出一个差不多的界面。真正拉开差距的是下面四个维度我给它们排了优先级产物形态 调试链路 组件生态 渲染方式。原因是前两项决定你上线之后能不能睡得着后两项决定你写代码时爽不爽——而写代码不爽可以忍上线出事忍不了。3.1 四个维度的横向对照维度IntraWEBuniGUITMS WEB Core事件执行位置服务端为主回发驱动服务端会话内浏览器本地执行部署产物需要运行中的服务端模块需要常驻服务端进程静态 HTML/JS/CSS 文件会话与并发会话状态在服务端需管理会话状态在服务端需管理无服务端会话压力在接口数据访问可直接连库可直接连库走 REST / 云数据库 / 其它语言接口调试手段IDE 断点为主IDE 断点为主浏览器 DevTools source map组件来源自有控件集自有控件集 丰富第三方封装 HTML 元素 FNC jQuery UI迁移成本老 VCL 项目低低中需要重做数据层适配移动端有限有限同一份代码可出 PWA/桌面壳这张表里我最想让人盯住的是「数据访问」那一行。前两套能直接连数据库意味着你可以把十年前的 DataModule 原样搬过来TMS WEB Core 不行浏览器里没有数据库驱动这回事你必须有一个 REST 层。教程里给了三条路传统数据库套 REST API、云数据库直接提供 REST 接口、以及用其它语言写 REST 服务。这三条路对应三种团队现状不是技术优劣问题。3.2 渲染方式带来的首屏与分享差异服务端渲染的方案首屏内容由服务端生成好再发下来理论上首屏更快、对搜索引擎更友好。但要注意「理论上」三个字一旦页面里塞了大量控件状态服务端拼 HTML 的时间也会涨首屏反而可能变慢。我在一个两百多个控件的表单页上量过服务端方案的响应时间里序列化和状态重建占了大头。浏览器执行的方案首屏需要先下载 JS 再执行第一次打开会有明显的一段空白。缓解手段很常规产物做压缩、脚本用 defer/async、加载期放一个静态骨架屏。TMS WEB Core 的产物是标准 JSWebpack、Vite 那一套优化思路基本都能借用这点比闭环的服务端框架灵活。分享和索引这一条常被忽略。浏览器执行的应用URL 路由归你控制可以做深链接服务端会话方案的路由往往和会话绑在一起把链接发给别人经常打开的是另一个状态。如果你们的系统要给外部用户用这个细节会反复咬人。3.3 组件生态与迁移成本怎么估IntraWEB 和 uniGUI 的控件更「Delphi 味」属性、事件命名和 VCL 高度一致老手几乎不用查文档。TMS WEB Core 的控件分几类封装 HTML 元素的 UI 控件、基于 HTML5 Canvas 的自绘控件、FNC 控件、以及 jQuery UI 控件。这套分层的好处是你能在需要的时候直接操作底层 DOM坏处是有些属性的行为和你熟悉的 VCL 不完全一样——比如定位方式就分绝对定位和相对定位两种选错了在不同分辨率下会歪得很难看。迁移成本的估算我有个粗暴办法数一数现有项目里有多少个「直接连库 复杂 SQL」的窗体。如果这类窗体占比超过三成改造成本会很高因为每个窗体的数据访问都要落到一个接口上如果大部分窗体是「读一张表 简单编辑」改造起来会快得多。3.4 调试链路Pas2JS 的映射决定体验这条是我认为最容易被低估的。TMS WEB Core 的代码最终是 JavaScript出问题时如果只能看编译后的产物那基本等于黑匣子。好在 Pas2JS 支持生成 source map浏览器 DevTools 里能直接对着 Pascal 源码打断点、看调用栈。但这里有个前提你得把 source map 打开而且浏览器不能缓存旧的脚本。我吃过一次亏——改了代码页面行为没变排查了半小时才发现是缓存里的旧 JS 在跑。后来养成习惯调试期一律开着 DevTools 的「禁用缓存」发布前再关掉。服务端方案在这条上省心因为断点就在 IDE 里变量窗口、调用栈、异常捕获全是原生的。代价是你看不到浏览器端发生了什么一旦问题出在 DOM 或样式层还是得开 DevTools。4. 从装环境到出产物一条可复现的上手路径教程对入门这块写得很省事只需要免费的 Delphi 社区版加上 TMS WEB Core 的试用版就够跑起来。我按这条路走过一遍中间卡了几次把顺序理顺之后其实很快。下面这条路径是我自己验证过的新手照着做能出一个能打开的页面熟手可以重点看参数那一节。4.1 环境只准备两样东西第一样是 IDE。社区版足够注意装的时候要选上目标平台支持不然新建项目列表里可能看不到对应模板。第二样是框架安装包装完在 IDE 里会多出一组项目模板和一个组件面板页。Lazarus 这条路教程里也写了适合不想装商业 IDE 的场景。我的建议是先在一台干净机器上把 IDE 和框架装通、跑起官方示例再往自己的工作机上折腾。混着装过多个版本 IDE 的机器组件包注册冲突是高频问题排查起来很不划算。4.2 四种项目模板怎么挑装好之后新建项目会看到四类模板名字很像但产物完全不同Web 应用最常规的一种产出一个静态站点目录扔到任意托管服务器就能访问。渐进式 Web 应用PWA在 Web 应用基础上加了 manifest 和 Service Worker可以「安装」到桌面或手机主屏支持离线缓存。Electron 桌面应用把同一份前端产物塞进 Electron 壳得到一个桌面程序。Miletus 桌面应用另一条桌面壳路线产物形态和 Electron 那条不一样。选哪个只看目标要给外部用户访问就 Web 或 PWA要给内部用户当桌面软件用就考虑桌面壳。我第一次做的时候贪心直接上了 PWA结果被 Service Worker 的缓存策略折腾了一下午——更新了代码但用户拿到的还是旧版。新手起步建议先用普通 Web 应用把链路跑通再往里加壳。4.3 命令行编译与 Pas2JS 的几个关键参数IDE 里点编译当然可以但真正要做自动化发布绕不开命令行。框架会为每个项目生成编译配置Pas2JS 是底层的编译器。下面这段是骨架示意实际路径和单元搜索路径以项目生成的构建脚本为准# 切到项目目录注意路径里别带空格Windows 下尤其容易出问题 cd /path/to/WebProject1 # -Tbrowser 指定目标是浏览器不是 node 也不是其它运行环境 # -Fu 逐个追加单元搜索路径RTL 是运行时库Core 是框架核心单元 # --sourcemap 生成映射文件DevTools 里才能对 Pascal 源码下断点 # -o 指定输出 JS 文件名一般和项目名保持一致不要随意改 pas2js -Tbrowser \ -Fu$TMSWEB/RTL \ -Fu$TMSWEB/Core/Source \ --sourcemap \ -ojs/WebProject1.js \ WebProject1.lpr几个参数值得单独说。-Tbrowser决定了生成代码的运行环境假设写错了会在浏览器里报一堆奇怪的全局对象缺失。-Fu是累加的少一个单元就会在编译期报「找不到单元」而不是运行期这点比 JS 生态友好。--sourcemap只在调试期开发布时可以关掉减小体积但关了之后线上问题就只能看压缩后的代码我的做法是线上也保留 map 文件、只是不对外暴露。教程里还提到预处理器和实用功能性函数前者用来做条件编译——我一般用它区分开发环境和生产环境的接口地址避免手动改配置改错。后者是一些跨平台的工具函数处理字符串、日期、编码转换时能省不少事。4.4 HTML 模板与 Pascal 代码怎么同步这是 TMS WEB Core 最有特色、也最容易搞混的一块。页面设计有两种方式一种是在 IDE 里拖控件、按绝对或相对定位摆好另一种是直接写 HTML 模板让控件挂到模板里的元素上。我的经验是布局复杂、要和设计稿对齐的页面走 HTML 模板交互密集、控件动态生成的页面走 IDE 拖拽。两种混用没问题但要搞清楚同步方向。教程里专门有一节讲自动同步 HTML 模板意思是 IDE 里的改动会写回模板文件——如果你的模板是从外部拿来的、还在被设计师改这个自动同步可能会覆盖掉对方的改动。我第一次就撞上了模板被覆盖后样式全乱找原因找了好久。稳妥做法是把模板文件纳入版本管理同步前后各提交一次出问题能对比差异。5. 配置阶段的踩坑清单五条现象、原因与解法下面这五条都是我自己撞过的按「现象 → 原因 → 解决」写新手可以直接对照排查熟手可以看看有没有共性。5.1 编译全绿浏览器打开却是一片白现象IDE 里编译没有任何报错输出目录里也有一堆文件用浏览器打开 index.html 就是白屏控制台可能有一行 404 或者干脆什么都没有。原因绝大多数情况是生成出来的 JS 没有被正确引用。要么是输出路径和 index.html 里的 script 标签对不上要么是构建脚本把 JS 输出到了另一个目录而 HTML 还指向老位置。解决打开 index.html 看 script 的 src再对着文件系统确认那个路径下真有文件。路径对不上的话回去检查构建配置里的输出目录两边改成一致。还有一种少见情况是 JS 加载了但入口函数没执行这时候在 DevTools 的 Sources 里搜一下应用启动的那段代码确认它确实被打进去了。5.2 本地一切正常传到托管服务器就 404现象本机用 IDE 的内置服务器打开完全正常把整个输出目录上传到托管服务器后首页能开但一堆资源 404或者点进二级页面直接挂。原因两个常见原因叠加。一是路径写成了绝对路径以/开头而站点被部署在子目录下路径就全错位了。二是大小写问题——本地是 Windows 文件系统不区分大小写托管服务器多半是 Linux区分大小写Main.js和main.js是两个文件。解决产物里的资源引用一律用相对路径不要用绝对路径开头。文件名统一小写构建脚本里加一步检查。上传前先在本地起一个区分大小写的静态服务器跑一遍能提前发现九成问题。5.3 断点打不上DevTools 里只能看到压缩后的代码现象在浏览器里想给某段 Pascal 逻辑打断点DevTools 只显示一堆混淆过的 JS或者显示的是 JS 但行号完全对不上。原因source map 没生成或者生成了但没被浏览器加载。也可能是浏览器缓存了旧版本的脚本map 文件版本和 JS 对不上。解决确认编译参数里带了生成 source map 的选项确认产物目录里存在对应的.map文件确认 JS 文件末尾有指向它的注释。然后在 DevTools 设置里打开「禁用缓存」重新加载。这一步做完还不行就看 Network 面板里 map 文件的请求是不是 404 了。5.4 接口在 Postman 里通在页面上报跨域现象同一个接口地址用接口调试工具请求一切正常页面上一点就报跨域错误控制台红一片。原因逻辑跑在浏览器里请求受同源策略管。接口调试工具不受这个限制所以它通不代表页面能通。另外带 Cookie 的请求还会触发预检服务端不处理 OPTIONS 请求一样会失败。解决服务端放行来源、放行方法、放行自定义头带凭证的请求还要显式允许凭证且来源不能写成通配符。开发期可以配一个本地代理把接口转发到同源路径下省去反复改服务端配置。5.5 列表页数据一多就卡滚动像幻灯片现象几十条数据流畅上千条就开始卡滚动明显掉帧低配机器上直接假死。原因一次性把所有行都渲染成 DOM 节点。浏览器里每个节点都是有成本的几千个节点加上样式计算卡是必然的。这在服务端渲染方案里反而不明显因为分页通常做在服务端。解决回到分页或者做虚拟滚动——只渲染视口内的行。数据量真的很大时把重计算挪到接口侧前端只负责展示。6. 结论什么团队该把 TMS WEB Core 当主力把前面这些收一收我的判断标准其实很短如果你已经有或者愿意做一个REST 接口层并且目标产物要跑在浏览器、手机、桌面多个壳里那 TMS WEB Core 值得当主力框架如果你的系统是内网重表单、团队里没人想碰接口层那服务端会话方案更省命。具体到人传统 Delphi 程序员想转 Web 前端这是目前阻力最小的一条路因为语言、IDE、调试习惯全都不用换要补的只有「浏览器里能做什么、不能做什么」这一层认知。反过来如果你是前端出身想用 Pascal我不太建议——生态和工具链的惯性不在这一边。一个具体技巧也是我现在的固定动作新项目第一个页面只做只读列表不做编辑、不做登录、不做路由。这个页面能把整条链路跑通——编译产物对不对、静态托管能不能访问、接口跨域通不通、source map 能不能断点。这五件事里任何一件出问题都会在后面变成大麻烦而在这个最小页面上排查成本是最低的。我上一个项目就是因为跳过了这步直接上完整功能结果发布当天才发现托管环境的路径问题回滚了两次。回过头看选框架这件事最贵的不是学习成本是上线之后改不动。教程这份 PDF 的价值也在这儿它把 TMS WEB Core 的项目类型、组件体系、模板同步、部署方式这些容易被跳过的细节都铺开了你先照着跑一遍最小链路再决定要不要押上去比看十篇评测都实在。资源就在那儿拿到手先跑通那个只读列表页剩下的判断你自己会有。希望帮到你。本文还有配套的精品资源点击获取