NativeScript WinterTC Android 工程构建指南：用 Android Studio 与 Gradle 打开并构建 winter_tc

导读

本文聚焦 NativeScript 仓库中 packages/winter-tc/android 目录下的 Android Studio 原生工程winter_tc，完整讲解它的打开方式、Gradle 构建流程与产物输出路径，并深入到Crypto.java、Utils.java等源码，说明该工程在 WinterTC 合规性中承担的加密与工具职责。读完本文，你将能够独立在 Android Studio 中打开、编译该工程，并理解其作为 NativeScript 原生桥接库的价值。

工程背景：WinterTC 合规性与 native 代码库

winter-tc是 NativeScript 仓库中的一个独立 package，其包级 README 明确说明：该库包含@nativescript/core所需的原生代码（Objective-C 与 Java），用于提供WinterTC（Web-interoperable Runtimes Community Group 测试合规性）。WinterTC 是一套旨在提升 Web 运行时互操作性的测试与合规标准，NativeScript 通过将平台 API 直接暴露给 JavaScript 运行时（并附带强类型）来支撑丰富的 TypeScript 开发体验，而 winter-tc 中的原生代码正是这套合规能力在 Android / iOS 侧的落地实现。

整个 package 由两部分原生工程组成：

本文只讨论 Android 侧工程，即 android/README.md 所描述的内容。

工程目录结构一览

packages/winter-tc/android/ ├── gradle/wrapper/ # Gradle Wrapper（jar + properties） ├── winter_tc/ # 主工程模块 │ └── src/main/ │ ├── AndroidManifest.xml │ └── java/org/nativescript/winter_tc/ │ ├── Crypto.java # WinterTC 加密原语实现 │ └── Utils.java # 工具函数（Base64、ByteBuffer 复制等） ├── gradle.properties # Gradle 全局设置 ├── settings.gradle # 模块声明 include ':winter_tc' ├── gradlew / gradlew.bat # Unix / Windows 包装脚本 └── README.md # 官方打开与构建说明

工程采用标准的 Android Gradle 项目布局：根目录是一个 Gradle 多模块项目，通过 settings.gradle 中的include ':winter_tc'声明唯一的子模块；仓库内同时提供了 Unix 与 Windows 双平台包装脚本（gradlew、gradlew.bat）以及固定的 Gradle Wrapper 配置，这意味着开发者无需预装指定版本的 Gradle 即可复现一致的构建环境。

如何在 Android Studio 中打开

依据 android/README.md 的官方指引，打开步骤如下：

1. 启动 Android Studio，选择菜单File → Open；
2. 在文件选择器中导航到packages/winter-tc/android/目录并打开；
3. 打开后，在窗口左侧的Project选项卡中，选择winter_tc模块即可查看其源码、Manifest 与 Gradle 配置。

Android Studio 会依据根目录的 Gradle Wrapper 自动解析并下载对应版本的 Gradle，完成同步后即可浏览Crypto.java、Utils.java等源码文件。

如何构建：assembleRelease 任务

同样依据官方文档，构建流程如下：

1. 在 Android Studio 窗口右侧选择Gradle选项卡；
2. 导航到android/winter_tc/Tasks/build/；
3. 执行assembleRelease任务；
4. 构建产物输出在./android/winter_tc/build/outputs/目录。

说明：文档中的android/winter_tc/路径对应于本仓库根目录下的packages/winter-tc/android/winter_tc/，即产物实际位于packages/winter-tc/android/winter_tc/build/outputs/。该输出目录下的outputs/aar/会生成可供消费的 AAR 归档，这也是该原生模块被 NativeScript 应用或@nativescript/core集成时使用的标准 Android 库格式。

在命令行中构建（等价方式）

除了 IDE 内执行任务，仓库自带的 Gradle Wrapper 也支持纯命令行构建，效果与 Android Studio 中的assembleRelease完全一致：

# 在 packages/winter-tc/android 目录下 ./gradlew :winter_tc:assembleRelease

Windows 用户改用gradlew.bat。assembleRelease会执行资源合并、Java 编译、ProGuard 混淆（如配置）与打包，最终产出 Release 变体的 AAR。若需调试版本，可对应执行assembleDebug。

关键 Gradle 配置说明

工程根目录的 gradle.properties 包含以下对构建有直接影响的设置：

源码纵深：winter_tc 在 WinterTC 合规中做了什么

winter_tc模块的 Java 源码全部位于org.nativescript.winter_tc包下（src/main/java），共两个类：Crypto.java与Utils.java。它们是 WinterTC 合规在 Android 侧的核心实现，支撑 JavaScript 运行时中 Web Crypto API 等标准接口的原生调用。

Crypto.java：WinterTC 加密原语

Crypto.java 通过 JNI/JS 桥接暴露给上层，实现了几组标准加密能力：

• randomUUID()：基于UUID.randomUUID()生成小写形式的随机 UUID，对应 Web 标准的crypto.randomUUID()；
• getRandomValues(ByteBuffer)：使用SecureRandom填充缓冲区，并分别处理堆内缓冲区与isDirect()直接缓冲区的两种写入路径，对应crypto.getRandomValues()；
• digest(mode, data)：按模式分发到 SHA-1（mode 0）、SHA-256（mode 1）、SHA-384（mode 2）、SHA-512（mode 4），结果以allocateDirect的直接字节缓冲返回，对应SubtleCrypto.digest()；
• generateKeyHMAC/signHMAC/verifyHMAC：基于javax.crypto.Mac实现 HMAC 密钥生成、签名与常数时间比较验证（Arrays.equals）；
• generateKeyRsaOAEP：使用RSAKeyGenParameterSpec.F4（65537 公钥指数）生成 RSA 密钥对；
• encryptRsaOAEP/decryptRsaOAEP：按 mode 0～3 分别映射到RSA/ECB/OAEPWithSHA-1AndMGF1Padding、SHA-256、SHA-384、SHA-512四种变换，加解密分别使用公钥与私钥，对应SubtleCrypto.encrypt()/decrypt()的 RSA-OAEP 算法。

从代码结构可以推断，Crypto.java是 Web Crypto 标准算法族在 Android 原生层的直接映射实现，WinterTC 合规测试会通过 JavaScript 侧调用这些原生方法并校验与标准实现的一致性。

Utils.java：桥接工具函数

Utils.java 提供两方面的辅助能力：

• copyToBuffer系列重载：将byte[]按指定 offset/length 复制进ByteBuffer，并支持rewind回绕选项，用于 JS 与 Java 之间安全的数据传递；
• atob/btoa：基于android.util.Base64.NO_WRAP实现 Base64 解码与编码，返回 UTF-8 字符串，对应 Web 标准atob()/btoa()全局函数。

AndroidManifest 与 ProGuard

AndroidManifest.xml 声明了READ_EXTERNAL_STORAGE与WRITE_EXTERNAL_STORAGE两个权限，且均带有android:maxSdkVersion="28"限制——即仅在 Android 9（API 28）及以下生效，适配旧版本的外部存储访问模型。

proguard-rules.pro 目前为空配置（仅注释模板）。由于该库需要通过原生桥接被 JavaScript 运行时反射调用，若未来启用混淆，通常需要为org.nativescript.winter_tc包下的公开静态方法补充 keep 规则，否则反射调用可能在 Release 构建中失效——这是此类桥接库的常见注意点。

关联开发工作流

关于整个 winter-tc 包（Android + iOS）的构建与联调，可以参考包级开发工作流文档：其中描述了在 macOS 上通过./build.sh一次性构建双平台、或通过./build.android.sh仅构建 Android 的脚本化流程，产物会汇总到./dist/package并打包为tns-core-modules-widgets-*.tgz；在应用侧则通过npm link的方式本地链接该插件包进行联调。该文档适用于整个包的集成流程，而本文所述的assembleRelease是针对 Android 子工程的最小构建单元。

验证与后续阅读

构建完成后，可在packages/winter-tc/android/winter_tc/build/outputs/中检查 AAR 产物是否生成，并留意构建日志中的任务执行情况。若需进一步了解 NativeScript 如何将平台 API 暴露给 JavaScript 运行时，可继续阅读 packages/core 中的相关模块；WinterTC 合规能力最终会通过@nativescript/core的运行时桥接被应用到真实应用中。