Apache Royale 0.9.12 配置参数详解

目标：系统讲解 Apache Royale 0.9.12 的配置参数。Royale 是 SDK 编译器形态，配置分三层：mxmlc 编译器命令行参数、Maven 插件（royale-maven-plugin）配置、SDK 自带配置文件（royale/js/node-config.xml）。本文对每个参数给出含义、实测取值与使用建议，另含 JVM 堆设置与 FAQ。所有参数均在 Ubuntu 22.04.5 + JDK 11 + Royale 0.9.12 环境实测。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS
• Java：OpenJDK 11.0.32.1
• Royale 版本：0.9.12（SDK 位于 /opt/royale/apache-royale-0.9.12-bin-js）
• 配置载体：编译器命令行参数 + Maven 插件配置 + SDK 配置文件
• 示例工程：/root/royale-hello/（Maven）、/root/royale-node-hello/（Node 目标）

二、前置条件

已按《Ubuntu 22.04 安装 Apache Royale 0.9.12 指南》安装 SDK 并配置环境：

export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
export PATH=$ROYALE_HOME/js/bin:$PATH
$ROYALE_HOME/js/bin/mxmlc --help | head -1

实测回显：

Apache Royale MXML and ActionScript Compiler (mxmlc)

三、配置形态总览

Royale 0.9.12 的配置由三层构成，实际使用时常按需组合：

四、mxmlc 编译器命令行参数详解

4.1 查看参数帮助

$ROYALE_HOME/js/bin/mxmlc -help <keyword>

例如查看输出类型相关参数：

$ROYALE_HOME/js/bin/mxmlc -help output-type

4.2 输出目标类型（-js-output-type）

参数：-js-output-type <string>

指定 JS 输出的目标类型。实测可取值：

$ROYALE_HOME/js/bin/mxmlc -js-output-type=node src/main/royale/HelloWorld.as

4.3 编译目标（-compiler.targets）

参数：-compiler.targets [target] [...]（别名 -targets，可重复）

指定本次编译的目标平台，多个目标以空格分隔、参数可重复。实测取值 JSRoyale（浏览器 JS）、JSNode（Node 后端）、SWF（Flash）等。Maven 插件 targets=JSRoyale 即映射为本参数。

$ROYALE_HOME/js/bin/mxmlc -compiler.targets=JSRoyale src/HelloRoyale.mxml

4.4 库路径（-compiler.external-library-path）

参数：-compiler.external-library-path [path-element] [...]（可重复）

指定编译时引用但不链接的 SWC 或目录列表，用于引入第三方组件库。多个路径以空格分隔，或重复传入：

$ROYALE_HOME/js/bin/mxmlc -compiler.external-library-path=/opt/lib/MyLib.swc src/HelloRoyale.mxml

4.5 源码路径（-compiler.source-path）

参数：-compiler.source-path [path-element] [...]（可重复）

指定 ActionScript 类层次根路径列表，编译器在此查找被引用但未显式导入的类源码。

$ROYALE_HOME/js/bin/mxmlc -compiler.source-path=/root/shared-as src/HelloRoyale.mxml

4.6 配置文件（-load-config / -js-load-config）

参数：-load-config <filename>（可重复）、-js-load-config <filename>（可重复）

加载编译器配置文件。-load-config 通用，-js-load-config 面向 JS 目标专用配置。Maven 构建实测即通过 -load-config=/root/royale-hello/target/compile-app-config.xml 加载插件生成的配置。

$ROYALE_HOME/js/bin/mxmlc -load-config=/opt/royale/custom-config.xml src/HelloRoyale.mxml

4.7 调试与优化（-compiler.debug / -js-output-optimization / -js-output）

• -compiler.debug（别名 -debug）：生成可调试产物。实测未加该参数时同时产出 bin/js-release（优化版）与 bin/js-debug（未压缩版）两个目录；该参数控制 debug 产物是否包含完整符号信息。
• -js-output-optimization [optimization] [...]（可重复）：JS 输出优化选项，js-release 目录产物即为压缩优化结果。
• -js-output <filename>：JS 输出文件名。实测注意：-js-output=demo.js 会把文件名当目录，产物仍落入 bin/js-release/；建议省略该参数使用默认输出，或交给 Maven 插件管理。

五、Maven 插件配置详解

5.1 packaging 与插件声明

packaging 必须为 swf（插件仅注册 swc/swf 的 LifecycleMapping），插件声明如下：

<packaging>swf</packaging>
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.royale.compiler</groupId>
            <artifactId>royale-maven-plugin</artifactId>
            <version>${royale.version}</version>
            <extensions>true</extensions>
            ...
        </plugin>
    </plugins>
</build>

<extensions>true</extensions> 启用插件的 LifecycleMapping，使 swf packaging 可驱动编译流程。

5.2 mainClass 与 targets

<configuration>
    <mainClass>HelloRoyale.mxml</mainClass>
    <targets>JSRoyale</targets>
</configuration>

• mainClass：应用入口 MXML/ActionScript 文件（相对 sourceDirectory，实测为 src）。
• targets：编译目标，对应命令行 -compiler.targets，实测 JSRoyale 编译浏览器 JS 应用。

5.3 compiler-jx 依赖

插件 <dependencies> 中必须引入 compiler-jx，否则报 Could not find tool group: Royale：

<dependencies>
    <dependency>
        <groupId>org.apache.royale.compiler</groupId>
        <artifactId>compiler-jx</artifactId>
        <version>${royale.version}</version>
    </dependency>
</dependencies>

5.4 框架依赖（Basic swc）

Maven 方案通过依赖引入框架 SWC（js classifier）：

<dependencies>
    <dependency>
        <groupId>org.apache.royale.framework</groupId>
        <artifactId>Basic</artifactId>
        <version>${royale.version}</version>
        <type>swc</type>
        <classifier>js</classifier>
    </dependency>
</dependencies>

首次构建自动从 Maven Central 拉取 Basic/Core/Collections/XML/Graphics/Language 与 typedefs 的 js classifier 构件。

5.5 自动生成的 compile-app-config.xml

mvn package 时插件在 target/ 生成 compile-app-config.xml 并以其调用 MXMLC（实测命令行见构建指南篇）。实测文件内容关键项：js-output-type=ROYALE、debug=false。需要自定义编译选项时，可修改此文件对应项或改用 -load-config 指向自己的配置文件。

六、SDK 配置文件详解

SDK 的 royale-asjs/frameworks/ 下提供三个配置文件：

asnodec 编译实测命令行等价于 mxmlc 加 -js-output-type=node 与 +configname=node，其中 +configname 即选择上述配置文件。自定义配置：用 -load-config <filename> 指定自己的配置 XML（可重复，后加载者覆盖前者的同名项）。

七、运行环境参数（JVM 堆）

mxmlc/asjsc/asnodec 均为 Java 进程，受 JVM 堆限制影响：

• 编译器进程默认堆上限实测为 -Xmx384m，处于 256–512MB 合理区间，一般工程无需调整。
• 大工程或大框架工程可在构建命令前用环境变量注入：

export MAVEN_OPTS="-Xms256m -Xmx512m"
cd /root/royale-hello && mvn package

• 直接运行编译器脚本时，可在脚本前追加 JVM 参数（脚本内部转发 JAVA_OPTS 时生效），或保持默认堆值。

八、参数总览

九、配置模板

常用命令模板：浏览器端构建用 mxmlc 默认输出；Node 端构建用 asnodec；Maven 工程统一走 mvn package。

export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
export MAVEN_OPTS="-Xms256m -Xmx512m"

# 浏览器端（Maven 工程，targets=JSRoyale 已在 pom 配置）
cd /root/royale-hello && mvn package

# 浏览器端（命令行，默认输出 bin/js-release 与 bin/js-debug）
cd /root/royale-hello && $ROYALE_HOME/js/bin/mxmlc src/HelloRoyale.mxml

# Node 端（命令行，产物 index.js 用 node 运行）
cd /root/royale-node-hello && $ROYALE_HOME/js/bin/asnodec src/main/royale/HelloWorld.as

十、常见问题

Q1：如何切换浏览器目标与 Node 目标？ 浏览器目标：mxmlc（-compiler.targets=JSRoyale）或 Maven targets=JSRoyale；Node 目标：asnodec（等价 -js-output-type=node + +configname=node），产物 index.js 用 node 直接运行。

Q2：如何同时保留 debug 与 release 产物？ 默认即可。实测 mxmlc 一次编译同时产出 bin/js-debug（未压缩）与 bin/js-release（压缩优化）两个目录；Maven 方案对应 target/javascript/bin/js-debug 与 js-release。

Q3：如何引入第三方 SWC 库？ 用 -compiler.external-library-path=/path/MyLib.swc（可重复），或在 Maven 工程中以 <type>swc</type> 依赖引入框架/第三方库（js classifier）。

Q4：-js-output=demo.js 为什么产物不在指定文件？ 该参数会把文件名当目录处理，产物仍出现在 bin/js-release/。省略该参数使用默认输出，或交由 Maven 插件管理输出路径。

Q5：如何指定自己的编译配置文件？ 用 -load-config <filename>（通用）或 -js-load-config <filename>（JS 目标）加载自定义 XML，多个配置文件按传入顺序叠加覆盖。

十一、参考链接

• Apache Royale 官方文档：https://royale.apache.org/
• Apache Royale 官方下载目录：https://downloads.apache.org/royale/
• royale-asjs 源码：https://github.com/apache/royale-asjs