Apache Royale 0.9.12 构建并运行示例应用指南

目标：从零构建并运行一个基于 Apache Royale 0.9.12 的最小示例应用（SDK 使用示例）。给出 Maven 工程与完整 pom.xml、HelloRoyale.mxml 示例源码、mvn package 与 mxmlc 命令行两种构建路径及产物解析，以及 Node 后端目标（asnodec）编译与 node index.js 运行的真实回显。所有命令与输出均在 Ubuntu 22.04.5 + JDK 11 环境实测通过。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS
Java：OpenJDK 11.0.32.1
构建工具：Apache Maven 3.6.3
Royale 版本：0.9.12（SDK 位于 /opt/royale/apache-royale-0.9.12-bin-js）
示例工程目录：/root/royale-hello/（Maven 工程）、/root/royale-node-hello/（Node 目标工程）
演示账号：root

二、前置条件

已按《Ubuntu 22.04 安装 Apache Royale 0.9.12 指南》安装 JDK 11、Node.js、npm、Maven 与 Royale SDK，并确认编译器可用：

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

实测回显：

Apache Royale MXML and ActionScript Compiler (mxmlc)

三、工程结构

浏览器端示例采用标准 Maven 布局：

royale-hello/
├── pom.xml
└── src/HelloRoyale.mxml

mkdir -p /root/royale-hello/src

四、示例源码（HelloRoyale.mxml）

创建 /root/royale-hello/src/HelloRoyale.mxml，声明一个显示文本标签的初始视图：

<?xml version="1.0" encoding="utf-8"?>
<js:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
                xmlns:js="library://ns.apache.org/royale/basic">
    <js:valuesImpl>
        <js:SimpleCSSValuesImpl/>
    </js:valuesImpl>
    <js:initialView>
        <js:View>
            <js:Label text="Hello Apache Royale 0.9.12!" y="24" x="24"/>
        </js:View>
    </js:initialView>
</js:Application>

xmlns:js="library://ns.apache.org/royale/basic"：Royale 基础组件命名空间。
js:Application 为应用根组件，js:initialView 声明初始视图，js:View/js:Label 为视图与文本组件。

五、方案 A：Maven 构建（官方推荐）

5.1 编写 pom.xml

创建 /root/royale-hello/pom.xml，使用 royale-maven-plugin 驱动编译：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>org.example</groupId>
    <artifactId>royale-hello</artifactId>
    <version>0.9.12</version>
    <packaging>swf</packaging>

    <properties>
        <royale.version>0.9.12</royale.version>
    </properties>

    <build>
        <sourceDirectory>src</sourceDirectory>
        <plugins>
            <plugin>
                <groupId>org.apache.royale.compiler</groupId>
                <artifactId>royale-maven-plugin</artifactId>
                <version>${royale.version}</version>
                <extensions>true</extensions>
                <configuration>
                    <mainClass>HelloRoyale.mxml</mainClass>
                    <targets>JSRoyale</targets>
                </configuration>
                <dependencies>
                    <dependency>
                        <groupId>org.apache.royale.compiler</groupId>
                        <artifactId>compiler-jx</artifactId>
                        <version>${royale.version}</version>
                    </dependency>
                </dependencies>
            </plugin>
        </plugins>
    </build>

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

关键点：

packaging 必须为 swf（插件只注册了 swc/swf 的 LifecycleMapping，royale/js 均报 Unknown packaging）。
插件 <dependencies> 必须引入 compiler-jx，否则报 Could not find tool group: Royale。
<mainClass> 指向示例 MXML 文件，<targets>JSRoyale</targets> 指定编译为浏览器 JavaScript 目标。

5.2 执行构建

cd /root/royale-hello
mvn package

实测回显（关键行）：

--- royale-maven-plugin:0.9.12:compile-app (default-compile-app) @ royale-hello ---
Executing MXMLC in tool group Royale with args: [-load-config=/root/royale-hello/target/compile-app-config.xml, -js-output=/root/royale-hello/target/javascript, -compiler.targets=JSRoyale, /root/royale-hello/src/HelloRoyale.mxml]
Oct 12, 2026 5:03:50 PM com.google.javascript.jscomp.LoggerErrorManager printSummary
INFO: 0 error(s), 0 warning(s), 97.2% typed
The project 'HelloRoyale' has been successfully compiled and optimized.
--- royale-maven-plugin:0.9.12:trust (default-trust) @ royale-hello ---
 - Creating new FlashPlayer security trust file at: /root/.macromedia/Flash_Player/#Security/FlashPlayerTrust/apache-royale-maven-plugin.cfg
 - Added directory '/root/royale-hello/target' to FlashPlayer security trust file at: /root/.macromedia/Flash_Player/#Security/FlashPlayerTrust/apache-royale-maven-plugin.cfg
--- royale-maven-plugin:0.9.12:package-js (default-package-js) @ royale-hello ---
[INFO] BUILD SUCCESS
[INFO] Total time:  24.276 s

5.3 构建产物

ls -lh /root/royale-hello/target/javascript/bin/js-release/
ls -lh /root/royale-hello/target/royale-hello-0.9.12.war

实测产物：

产物	大小	说明
`target/javascript/bin/js-release/HelloRoyale.js`	81509 B	压缩优化后的浏览器 JS 应用
`target/javascript/bin/js-release/HelloRoyale.min.css`	小	应用样式
`target/javascript/bin/js-release/index.html`	小	应用入口页
`target/javascript/bin/js-debug/HelloRoyale.js`	6880 B	未压缩可调试版本
`target/royale-hello-0.9.12.war`	22566 B	内含 js-release 三件套，可直接部署到 Web 服务器
`target/compile-app-config.xml`	小	插件自动生成的编译配置（js-output-type=ROYALE、debug=false）

首次构建会从 Maven Central 自动下载框架 SWC（Basic/Core/Collections/XML/Graphics/Language 与 typedefs 的 js classifier 构件）。

六、方案 B：mxmlc 命令行构建（SDK 自带编译器）

6.1 环境变量

export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs

6.2 执行编译

cd /root/royale-hello
time $ROYALE_HOME/js/bin/mxmlc src/HelloRoyale.mxml

实测回显：

Using Royale Compiler codebase: /opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/js/bin/../..
Using Royale SDK: /opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
MXMLJSC
+royalelib=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/frameworks
-sdk-js-lib=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/frameworks/js/Royale/generated-sources
src/HelloRoyale.mxml
Oct 12, 2026 4:50:47 PM com.google.javascript.jscomp.LoggerErrorManager printSummary
INFO: 0 error(s), 0 warning(s), 97.3% typed
The project 'HelloRoyale' has been successfully compiled and optimized.
12.110269487 seconds

6.3 构建产物

ls -lh /root/royale-hello/bin/js-release/
ls -lh /root/royale-hello/bin/js-debug/

实测产物：

产物	大小	说明
`bin/js-release/HelloRoyale.js`	79630 B	压缩优化版
`bin/js-release/HelloRoyale.min.css` + `index.html`	小	应用样式与入口页
`bin/js-debug/HelloRoyale.js`	6880 B	未压缩可调试版

💡 说明：mxmlc 不带 -js-output 时，产物默认输出到工程根 bin/js-release 与 bin/js-debug；编译时长约 12 秒。

七、验证浏览器端产物

浏览器目标 JS 依赖 DOM（HTMLElement），不能用 node require 直接运行，语法校验用 Node 内置的 --check：

node --check /root/royale-hello/target/javascript/bin/js-release/HelloRoyale.js
node --check /root/royale-hello/bin/js-release/HelloRoyale.js

实测结果：两条命令均无输出，退出码 0，即语法通过。浏览器端实际运行方式：将 index.html 与对应 JS/CSS 放到 Web 服务器（或直接部署 royale-hello-0.9.12.war）后，用浏览器打开入口页。

八、Node 后端目标：编译与运行

Royale 可把 ActionScript 编译为 Node.js 模块，在服务器上以 node 直接运行。

8.1 准备 Node 工程

mkdir -p /root/royale-node-hello/src/main/royale
cp /opt/royale/apache-royale-0.9.12-bin-js/royale-asjs/examples/node/HelloWorld/src/main/royale/HelloWorld.as /root/royale-node-hello/src/main/royale/

HelloWorld.as 源码：

package {

public class HelloWorld {

    public function HelloWorld() {
        console.log("Hello Royale World!")
    }

}

}

8.2 编译

asnodec 即 mxmlc 加 -js-output-type=node 与 +configname=node 的封装脚本：

cd /root/royale-node-hello
export ROYALE_HOME=/opt/royale/apache-royale-0.9.12-bin-js/royale-asjs
$ROYALE_HOME/js/bin/asnodec src/main/royale/HelloWorld.as

实测回显：

WARNING: externs/zlib.js:384: WARNING - name module is not defined in the externs.
module.exports = zlib;
Oct 12, 2026 4:51:29 PM com.google.javascript.jscomp.LoggerErrorManager printSummary
WARNING: 0 error(s), 68 warning(s), 97.5% typed
The project 'HelloWorld' has been successfully compiled and optimized.
11.071976096 seconds

8.3 运行

cd /root/royale-node-hello/bin/js-release && node index.js
cd /root/royale-node-hello/bin/js-debug && node index.js

实测输出（两个版本一致）：

Hello Royale World!

退出码均为 0，说明 Node 目标应用编译、运行全部通过。externs/zlib.js 的 WARNING 与 68 条警告为类型定义提示，不影响产物运行。

九、注意事项

⚠️ 注意：

Maven 方案 packaging 必须写 swf，royale/js 均不支持（Unknown packaging）。

插件必须声明 compiler-jx 依赖，否则报 Could not find tool group: Royale。

浏览器端 JS 产物依赖 DOM，node require 会抛 ReferenceError，请用 node --check 做语法校验；需要服务器端运行请走第八节 Node 目标。

mxmlc 是 Java 进程，可用 MAVEN_OPTS="-Xms256m -Xmx512m" 约束构建 JVM 堆（编译器默认 -Xmx384m，一般无需调整）。

十、常见问题

Q1：mvn package 报 Unknown packaging: royale 或 Unknown packaging: js？ packaging 只能使用 swf。royale-maven-plugin 只注册了 swc/swf 的 LifecycleMapping，改成 <packaging>swf</packaging> 即可。

Q2：mvn package 报 Could not find tool group: Royale？ 插件缺少编译器工具组实现。在 royale-maven-plugin 的 <dependencies> 中加入 org.apache.royale.compiler:compiler-jx:0.9.12（工具组在该 jar 的 META-INF/services/org.apache.flex.tools.FlexToolGroup 中注册）。

Q3：mxmlc 加 -js-output=demo.js 后产物不在指定文件？ -js-output 参数会把文件名当目录处理，产物仍出现在 bin/js-release/ 下。建议省略该参数使用默认输出，或交给 Maven 插件管理输出路径。

Q4：node require 浏览器端 JS 产物报 ReferenceError: HTMLElement is not defined？ 浏览器目标产物依赖 DOM，只能在浏览器运行。服务器端运行请用 asnodec 编译 Node 目标（第八节）。

Q5：编译输出大量 WARNING 影响构建吗？ 不影响。实测 0 error 即可成功产出（97%+ typed）；externs/zlib.js 等 WARNING 是闭包编译器的类型定义提示。

十一、参考链接

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