Apache Flex 4.16.1 模块化与进阶实战详解

Apache Flex 4.16.1 模块化与进阶实战：RSL 运行时共享库把产物从 511 KB 压到 58 KB、Module 模块拆分与 ModuleLoader 主从通信、optimizer 瘦身、asdoc 文档生成与 HTML wrapper 发布，全部命令与回显均实测通过。

Apache FlexApache Flex2026/10/15

Apache Flex 4.16.1 模块化与进阶实战详解

目标：把单文件演示工程升级为可维护的模块化 Flex 工程：用 RSL 运行时共享库把产物从 511 KB 压缩到 58 KB（实测 89% 削减），用 mx:Module 把业务功能拆成独立 SWF 并实现主应用通信，用 optimizer 做发布前瘦身，用 asdoc 生成 API 文档并完成 HTML wrapper 静态发布。以下全部命令与回显均已在 Ubuntu 22.04（x86_64）、OpenJDK 1.8.0_504、Apache Flex SDK 4.16.1（build 20171115）实测通过。

Flex 工程的规模一旦超过单页演示，三类问题立刻浮现：产物体积失控（Spark/MX 框架库默认静态嵌入，产物 500 KB 起步）、业务无法拆分（所有代码挤在一个 SWF 里，改一行重发全量）、发布缺乏工程化（没有文档、没有标准播放页）。本文按「体积 → 拆分 → 瘦身 → 文档 → 发布」的顺序逐个解决，每个环节都给出可直接复现的命令、实测回显与验证手段。

一、环境信息

  • 操作系统：Ubuntu 22.04.5 LTS（x86_64）
  • JDK：OpenJDK 1.8.0_504（asdoc 章节 JIT 必须，其余环节 11/17 亦可）
  • SDK：Apache Flex 4.16.1（build 20171115），安装于 /opt/apache-flex-sdk-4.16.1-bin，playerglobal 32.0，含官方 RSL 文件
  • 基础工程：/root/hello（HelloWorld 应用）、/root/moduledemo（模块化演示）、/root/libdemo（SWC 库）
  • 验证工具：file + bin/swfdump + ls -l（体积对比）

确认 RSL 素材在位（ant 安装器随包提供，实时回显）：

ls -l /opt/apache-flex-sdk-4.16.1-bin/frameworks/rsls/ | head -8

total 3452
-rw-r--r-- 1 root root 245936 Nov 15  2017 advancedgrids_4.16.1.20171115.swf
-rw-r--r-- 1 root root  13242 Nov 15  2017 apache_4.16.1.20171115.swf
-rw-r--r-- 1 root root 254717 Nov 15  2017 charts_4.16.1.20171115.swf
-rw-r--r-- 1 root root 137851 Nov 15  2017 experimental_4.16.1.20171115.swf
-rw-r--r-- 1 root root  17054 Nov 15  2017 experimental_mobile_4.16.1.20171115.swf
-rw-r--r-- 1 root root 564754 Nov 15  2017 framework_4.16.1.20171115.swf
-rw-r--r-- 1 root root 530253 Nov 15  2017 mx_4.16.1.20171115.swf

💡 技术拓展：Flex 拆分体积的两条路线对比——

方案机制首屏收益适用
RSL 运行时共享库框架库改为运行时按 URL 加载的独立 SWF单页部署产物 -89%（实测）多页面共享同一框架，浏览器可缓存
Module 模块化业务代码拆成按需加载的子 SWF主应用只含入口功能模块化、延迟加载
optimizer 瘦身移除调试元数据等冗余标签单文件 -0.2% 左右（实测）发布前最后一步

本文三者全部使用：RSL 解决框架库共享、Module 解决业务拆分、optimizer 做最终瘦身，三者叠加才是完整方案。

二、RSL 运行时共享库

2.1 原理与开关

默认编译把 framework、spark、mx、textLayout、osmf 等框架库完整嵌入 SWF（产物 511 KB 量级）。flex-config.xml 的 runtime-shared-library-path 段已为每个框架 SWC 预声明了对应的 RSL 文件名（如 framework.swc 绑定 framework_4.16.1.20171115.swf），命令行一个开关即可切换链接方式：-static-link-runtime-shared-libraries=false 表示「不把运行时共享库静态打进产物」。

2.2 实测对比

同一个 HelloWorld.mxml，先默认静态编译再切 RSL 编译（实测回显）：

cd /root/hello
mxmlc HelloWorld.mxml 2>&1 | tail -1
mxmlc -static-link-runtime-shared-libraries=false HelloWorld.mxml 2>&1 | tail -1

/root/hello/HelloWorld.swf (511460 bytes)
/root/hello/HelloWorld.swf (58279 bytes)

511460 → 58279 字节，削减 88.6%。用 swfdump -abc 查看产物常量池，确认 RSL 文件名引用已写入（实测每个 RSL 名各出现 2 次）：

/opt/apache-flex-sdk-4.16.1-bin/bin/swfdump -abc HelloWorld.swf 2>/dev/null | grep -oE "(framework|mx|spark)_4.16.1.20171115.swf" | sort | uniq -c

      2 framework_4.16.1.20171115.swf
      2 mx_4.16.1.20171115.swf
      2 spark_4.16.1.20171115.swf

2.3 部署形态与验证点

RSL 构建的部署目录要求：应用 SWF 与 frameworks/rsls/ 下被引用的 RSL 文件保持相对路径可达（默认 URL 是相对应用的 rsls/ 或 SDK 实际相对路径，按 flex-config 声明为准）。验证点三条：

  1. 产物体积量级应为 58 KB 上下（静态应约 511 KB）。
  2. swfdump -abc 能在常量池中看到 RSL 文件名。
  3. 浏览器端首次加载需能取到对应 RSL 文件（404 会黑屏，这是 RSL 方案最常见的线上事故，发布前逐文件核对）。

⚠️ 注意：RSL 削减的是「每个页面重复下载框架库」的成本，换来的是部署目录多出约 3.4 MB 的 RSL 文件集（实测 rsls 目录 total 3452 KB）。单页面一次性使用、或完全离线单文件分发的场景，静态链接反而更合适。

三、Module 模块化

3.1 模块与主应用

Module 是 Flex 的「子应用」机制：模块 SWF 与主应用共享框架库（配合 RSL 效果最佳），主应用用 mx:ModuleLoader 按 URL 按需加载。两个源文件如下。

/root/moduledemo/GaugeModule.mxml（业务模块全文）：

<?xml version="1.0" encoding="utf-8"?>
<mx:Module xmlns:mx="http://www.adobe.com/2006/mxml" width="280" height="120">
    <mx:Script>
        <![CDATA[
            public function setValue(v:Number):void {
                gauge.text = v.toFixed(1) + " %";
            }
        ]]>
    </mx:Script>
    <mx:Panel title="模块: 仪表盘" width="100%" height="100%">
        <mx:Label id="gauge" text="0.0 %" fontSize="20"/>
    </mx:Panel>
</mx:Module>

/root/moduledemo/ModuleApp.mxml（主应用全文）：

<?xml version="1.0" encoding="utf-8"?>
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml" width="320" height="180" creationComplete="init()">
    <mx:Script>
        <![CDATA[
            import mx.events.ModuleEvent;

            private function init():void {
                loader.addEventListener(ModuleEvent.READY, onReady);
            }
            private function onReady(e:ModuleEvent):void {
                log.text = "模块已加载: " + e.module.url;
            }
            private function push():void {
                var m:Object = loader.child;
                if (m != null && m.hasOwnProperty("setValue")) {
                    m.setValue(66.6);
                } else {
                    log.text = "模块尚未就绪";
                }
            }
        ]]>
    </mx:Script>
    <mx:ModuleLoader id="loader" url="GaugeModule.swf" width="280" height="120"/>
    <mx:Button label="推送 66.6" click="push()" y="130"/>
    <mx:Label id="log" x="10" y="160" width="300"/>
</mx:Application>

逐项说明：模块用 mx:Module 作根标签，对外暴露 setValue() 公共方法；主应用监听 ModuleEvent.READY 拿加载完成事件，通过 loader.child 访问模块实例——这里必须把 child 声明为 Object 并用 hasOwnProperty 探测方法，原因见 3.2 节坑一。

3.2 两个实测坑

坑一：静态类型访问模块方法编译失败。 主应用里写 loader.child.setValue(66.6) 直接报（实测回显）：

Error: Attempted access of inaccessible property setValue through a reference with static type mx.core:IFlexDisplayObject.

loader.child 的静态类型是 IFlexDisplayObject，编译器拒绝调用未知方法。修复：先转 Object 再 hasOwnProperty 探测（3.1 节主应用写法），运行时按实际加载的模块调用。

坑二：ModuleEvent 未 import 编译失败。 事件类型只在 MXML 内联事件里可用，Script 块中使用必须显式导入，漏写报（实测回显）：

Error: Type was not found or was not a compile-time constant: ModuleEvent.

修复：Script 首行加 import mx.events.ModuleEvent;。

3.3 编译与验证

模块与主应用都按普通 SWF 编译（模块无需特殊编译开关）：

cd /root/moduledemo
mxmlc GaugeModule.mxml 2>&1 | tail -1
mxmlc ModuleApp.mxml 2>&1 | tail -1
ls -l *.swf

/root/moduledemo/GaugeModule.swf (287591 bytes)
/root/moduledemo/ModuleApp.swf (289419 bytes)
-rw-r--r-- 1 root root 287591 Oct 15 08:32 GaugeModule.swf
-rw-r--r-- 1 root root 289419 Oct 15 08:32 ModuleApp.swf

用 swfdump 验证模块产物结构——模块入口的 FrameLabel 是 _GaugeModule_mx_core_FlexModuleFactory（FlexModuleFactory 即模块工厂，与普通应用的 SystemManager 入口不同，这是判定「编译出来的是模块」的直接证据）：

/opt/apache-flex-sdk-4.16.1-bin/bin/swfdump GaugeModule.swf 2>/dev/null | grep FrameLabel

  <FrameLabel label='_GaugeModule_mx_core_FlexModuleFactory'/>
  <FrameLabel label='GaugeModule'/>

验证点小结：两个 SWF 编译成功、模块入口为 FlexModuleFactory、主应用常量池中含 GaugeModule.swf 字符串（ModuleLoader 的加载 URL）。发布时两个 SWF 放同一目录（ModuleLoader 的 url 是相对路径）。

四、发布前瘦身：optimizer

optimizer 移除 SWF 中的调试元数据等冗余内容。先看它的用法帮助（实测回显）：

/opt/apache-flex-sdk-4.16.1-bin/bin/optimizer -help 2>&1 | head -10

Apache Flex Optimizer
Version 4.16.1 build 20171115
Copyright 2017 The Apache Software Foundation.


Usage: java flex2.tools.Optimizer [options] targets
  targets              SWF files
  -o <output> <input>  perform optimization on the input SWF file and write the output to the output file
  -o <output> -input <input>  perform optimization on the input SWF file and write the output to the output file

对模块产物瘦身（实测回显）：

cd /root/moduledemo
/opt/apache-flex-sdk-4.16.1-bin/bin/optimizer -input GaugeModule.swf -output GaugeModule-opt.swf 2>&1 | tail -1
ls -l GaugeModule*.swf

GaugeModule-opt.swf (287103 bytes)
-rw-r--r-- 1 root root 287103 Oct 15 08:32 GaugeModule-opt.swf
-rw-r--r-- 1 root root 287591 Oct 15 08:32 GaugeModule.swf

287591 → 287103 字节，削减 488 字节（比例小，因为演示工程本就没有调试信息；带 -compiler.debug=true 编译的产物瘦身比例会明显更高）。构建流水线的顺序建议：mxmlc 静态/RSL 编译 → optimizer 瘦身 → swfdump 验证 → 发布。

五、API 文档生成：asdoc

asdoc 从源码注释生成 HTML API 文档。实测前置条件：JDK 8——asdoc 启动脚本向 JVM 传入 -Xbootclasspath/p 选项，JDK 9+ 已移除该选项会直接拒绝启动（实测报错与根因见编译器详解篇第九章）。本文在 OpenJDK 1.8.0_504 下执行（实测回显）：

cd /root/hello && mkdir -p asdoc-out
asdoc -source-path . -doc-classes HelloWorld -output /root/hello/asdoc-out 2>&1 | tail -2

Warning: Could not get charToByteConverterClass!
Documentation was created in /root/hello/asdoc-out/

（charToByteConverterClass 是 JDK 8 下 asdoc 的已知无害警告，可忽略。）核对产物（实测回显）：

ls asdoc-out | head -8
ls -l asdoc-out/index.html

AC_OETags.js
HelloWorld.html
all-classes.html
all-index-A.html
all-index-B.html
all-index-C.html
all-index-D.html
all-index-E.html
-rw-r--r-- 1 root root 2355 Oct 15 08:33 asdoc-out/index.html

验证点：index.html（入口）、HelloWorld.html（类文档）、all-index-*.html（字母索引）齐全即生成成功。-source-path 指源码根，-doc-classes 显式列出要出文档的类（与 compc 的 -include-classes 同一语义）。

六、发布：HTML wrapper 与静态服务

6.1 wrapper 文件集

发布页来自 flexTasks 的 html-wrapper 任务（生成过程与两个坑见快速入门篇第四章），最终文件集（实测）：

ls /root/hello/wrapper/

history
index.html
swfobject.js

index.html 用 SWFObject 探测 player 版本并嵌入 SWF；history/ 支持浏览器前进后退；swfobject.js 是嵌入器本体。RSL 构建的产物发布时，需把 frameworks/rsls/ 中被引用的文件一并按相对路径放入（见 2.3 节）。

6.2 静态服务实测

用任意静态 HTTP 服务发布 wrapper 目录（实测用 Python 内置服务器）：

cd /root/hello/wrapper && nohup python3 -m http.server 8000 >/tmp/httpd.log 2>&1 &
curl -sI http://127.0.0.1:8000/index.html | head -3

HTTP/1.0 200 OK
Server: SimpleHTTP/0.6 Python/3.10.12
Date: Thu, 15 Oct 2026 08:16:39 GMT

⚠️ 注意：SWF 必须与 index.html 同目录（或在其引用的相对路径上）。实测把 SWF 留在 wrapper 外层时访问 http://127.0.0.1:8000/ant-hello.swf 返回 HTTP/1.0 404 File not found，复制进 wrapper 后同 URL 返回 200。验证结束停掉测试服务（kill %1）。

6.3 发布清单（checklist）

  1. 产物通过 file + swfdump 验证（版本、入口 FrameLabel、类清单）。
  2. RSL 构建时：应用 SWF、index.html、swfobject.js、history/、被引用的全部 RSL 文件相对路径齐全。
  3. Module 构建时：主应用 SWF 与全部模块 SWF 同目录。
  4. 发布后抽查 HTTP 状态码：index.html 与每个 SWF 均应 200。
  5. 服务器端无需常驻进程——静态文件服务即可，Nginx/Caddy/内置 http.server 均可承载。

七、常见问题（FAQ）

Q1：RSL 构建的页面打开后黑屏或加载失败？ 九成是 RSL 文件 404。核对部署目录里 frameworks/rsls/ 被引用文件是否存在、相对路径是否与 flex-config 声明一致；浏览器开发者工具的 Network 面板逐个核对状态码。彻底解决不了就回退静态链接（去掉 -static-link-runtime-shared-libraries=false），体积换稳定。

Q2：模块 SWF 编译出来了，主应用运行时却加载不到？ 排查三处：ModuleLoader 的 url 是否与部署目录结构一致（相对路径）；两个 SWF 是否在同一域名与端口下（跨域会被 Flash 安全沙箱拦截，需要 crossdomain.xml）；模块与主应用的框架库链接方式是否一致（主应用 RSL 化后，模块也要用同样的 -static-link-runtime-shared-libraries=false 编译，否则框架类版本冲突）。

Q3：optimizer 报 Use 'optimizer -help'？ 参数写法不对。optimizer 的正确形态是 -input <input> -output <output>（或 -o <output> <input>），实测 -keep-as3-metadata="" 这类老式写法会触发该提示。先跑 optimizer -help 核对当前版本用法再写命令。

Q4：asdoc 报 Could not create the Java Virtual Machine？ JDK 版本问题：-Xbootclasspath/p 选项在 JDK 9+ 被移除，asdoc 启动脚本依赖它。把 JAVA_HOME 指向 OpenJDK 8 重跑（编译器详解篇第九章有完整实测报错与结论）。

Q5：模块改了一行代码，必须重发整个应用吗？ 不需要，这正是 Module 的价值：只重编模块（mxmlc GaugeModule.mxml），替换部署目录里的模块 SWF 即可；主应用、RSL、其余模块都不动。唯一例外是共享类签名变化（模块与主应用都引用的公共库改动），那需要两边一起重编。

Q6：怎么验证模块真的编译成了模块而不是普通应用？ 看 swfdump 的 FrameLabel：模块入口是 _GaugeModule_mx_core_FlexModuleFactory（FlexModuleFactory），普通应用是 _HelloWorld_mx_managers_SystemManager（SystemManager）。3.3 节有完整实测回显。

八、参考链接

  1. Apache Flex 官方主页：https://flex.apache.org/
  2. Flex 4.16.1 发行说明：https://downloads.apache.org/flex/4.16.1/RELEASE_NOTES
  3. Module 与 ModuleLoader 说明（Apache Flex Wiki）：https://cwiki.apache.org/confluence/display/FLEX/Modules
  4. RSL 运行时共享库说明：https://cwiki.apache.org/confluence/display/FLEX/Runtime+Shared+Libraries
  5. asdoc 使用指南：https://cwiki.apache.org/confluence/display/FLEX/ASDoc
  6. 本专栏《Apache Flex 4.16.1 快速入门与集成示例》（HTML wrapper 生成与 flexTasks 集成）、《Apache Flex 4.16.1 mxmlc 与 compc 编译器详解》（JDK 兼容性与 JVM 参数）