更精简的 sgcWebSockets 构建 — 排除内嵌的 JS 资源

2026年5月20日 · 功能特性

分析其可执行文件大小的客户长期以来都会提出一个问题:«为什么添加 sgcWebSockets 后我的 EXE 变大了?»。这种增长的一部分来自 sgcWebSockets 运行时包默认嵌入的一个资源文件:sgcResources.RES。它包含 JavaScript 客户端打包文件,sgcWebSockets 服务器可以通过 HTTP 将其交付给远程浏览器 — 而大多数 Delphi 和 C++Builder 应用程序从未使用过这一功能。

从 sgcWebSockets 2026.6 开始,你可以选择不包含它。源代码版的 Setup 在选项页中新增了一个 Include Resources 复选框;取消勾选后,会在编译运行时包之前取消定义 sgcVer.inc 中新增的 SGC_RESOURCES 编译指令。该资源根本不会被链接进来 — 既不会进入 BPL,也不会进入你客户的 EXE。

会移除什么

sgcWebSockets 源代码中的 {$R} 指令现在被包裹在 {$IFDEF SGC_RESOURCES} 中:

// sgcWebSocket_Protocol_Base_Server.pas
{$IFDEF SGC_RESOURCES}
{$R sgcResources.RES}      // sgcWebSockets JS client bundle
{$ENDIF}

当 SGC_RESOURCES 未定义时,链接器没有任何内容可嵌入。该资源会从每一个链接源代码的可执行文件中彻底消失。

何时不需要这个资源

只有当 sgcWebSockets 服务器实际向远程浏览器交付内嵌的 JS 客户端时,才需要这个内嵌的打包文件。这种情况发生在使用 TsgcWSProtocol_JS_* 组件时,或任何通过返回内嵌 JavaScript 来响应 GET /sgcwebsockets.js 的服务器上。

以下情况不需要它:

Delphi / C++Builder WebSocket 客户端 — 数据在原生代码中被消费,从不进入浏览器。
原生到原生的服务器 — 客户端同样是 Delphi / C++Builder 应用的服务器。
提供自定义 JS 的 WebSocket 后端 — 如果你交付自己的 JavaScript 客户端(自己的打包工具、自己的 CDN),内嵌的那一份就是负担。
MQTT、AMQP、STOMP、WAMP、MCP 以及仅协议的服务器 — 它们都不使用内嵌的 JS 客户端。

如何启用

最简洁的方式是通过安装程序。当你运行 sgcWebSockets 源代码版安装程序时,点击 Options 按钮并取消勾选新增的条目:

[ ] Include Resources

安装程序会在编译任何包之前,将 sgcVer.inc 中的 {$DEFINE SGC_RESOURCES} 行重写为 {.$DEFINE SGC_RESOURCES},这样生成的设计时和运行时 BPL 都不会包含内嵌的打包文件。

如果你已经安装了 sgcWebSockets 并希望手动修改,请打开 <sgc-install-folder>\Source\sgcVer.inc,找到这一行:

{$DEFINE SGC_RESOURCES} { RESOURCES }

然后用大括号注释掉:

{.$DEFINE SGC_RESOURCES} { RESOURCES }

随后重新构建运行时 / 设计时包以及你的应用程序。在 IDE 中访问 Project > Build All Projects,或者运行你常用的构建脚本。

测量节省的体积

如果你想在自己的项目中确认节省的体积,可以在修改前后生成详细的链接器映射文件。重新构建后,打开生成的 *.map 文件并滚动到资源部分 — sgcResources.RES 应该已经消失。sgcWebSocket_Protocol_Base_Server 的 .text 模块大小也会略微减小,因为加载该资源的辅助代码会被作为死代码消除。

具体能节省多少取决于你的构建配置以及所使用的 sgcWebSockets 版本,但在典型的仅客户端构建中,EXE 体积会明显缩小。如果将此选项与已有的版本级开关结合使用(用 {$UNDEF SGC_EDT_ENT} 移除 WebAuthn / HTTP2 / OAuth 服务器,或者在仅客户端的代码中以 uses sgcWebSocket_Client 替代 uses sgcWebSocket),总的体积削减可以相当可观。

向后兼容性

sgcVer.inc 中的默认值仍然是 {$DEFINE SGC_RESOURCES},因此现有项目可以完全像以前一样继续编译和运行。新标志严格遵循默认启用、显式选择不包含的原则:除非你通过安装程序复选框或自行编辑 sgcVer.inc 显式禁用该资源,否则什么都不会改变。

如果你禁用了 SGC_RESOURCES,然后调用了试图提供内嵌 JS 客户端的服务器方法(例如 TsgcWSProtocol_JS_* 响应处理器),你会得到一个干净利落的 EResNotFound — 这是一个明显的信号,说明你关闭了实际需要的东西。只需重新启用该 define 并重新构建即可。

可用性

该新选项随 sgcWebSockets 2026.6 一起发布,仅在源代码版安装程序中提供(Standard、Professional 和 Enterprise)。Trial 安装程序仍然保留内嵌资源,以便内嵌的 JS 客户端演示能够开箱即用。

拥有有效订阅的客户可以从客户专区获取新版本。有问题或对进一步的体积削减开关有建议?联系我们 — 你会收到编写代码的人的回复。