构建与发布

环境要求

工具	版本
Node.js	>= 20
pnpm	>= 10
JDK	21
Android SDK	最新（compileSdk 36）
Android NDK	27.0.12077973（CI 固定值）
CMake	3.22.1（CI 固定值）

一键构建

pnpm install
pnpm build:android
cd android && ./gradlew assembleDebug

产物位于 android/app/build/outputs/apk/debug/，按 ABI 分包。

分步构建

pnpm build:web                  # 前端 Vite 构建 → dist/capacitor
npx cap sync android            # 同步 Capacitor 工程
pnpm build:android:node         # 内置 Node API Bundle
pnpm prepare:android:embedded   # 准备嵌入资源（libnode.so 等）
npx cap open android            # Android Studio 打开

构建管线详解

步骤	做了什么
postinstall	修补 nodejs-mobile-cordova 的 build.gradle：适配 Capacitor 的 assets/public、限制原生构建只在 app 模块执行、替换调试日志开关
build:web	Vite 生产构建到 dist/capacitor，terser 压缩并移除 console.log，外部化桌面端原生模块
cap sync android	把 Web 产物与 Capacitor 插件同步进 Android 工程
build:android:node	esbuild 将 API/mobile-entry.ts 打包为 CJS / ES2019 的 main.js；拷贝 Enhanced API 及其全部运行时依赖到 vendor/，并逐文件转译为 ES2019 CJS 以兼容 nodejs-mobile
prepare:android:embedded	拷贝 cordova 桥接到 android/app/libs/cdvnodejsmobile；解压四个 ABI 的 libnode.so.gz；修补 NodeJS.java；同步内嵌 node 工程到 assets/www/nodejs-project
gradlew assembleDebug/Release	Gradle 按 ABI 分包产出 APK

为什么 libnode.so 是 gz 提交

四个 ABI 的 libnode.so 体积巨大，仓库中以 .gz 形式存储，由 prepare:android:embedded 在构建时解压。跳过该步骤会导致链接失败。

签名配置

Release 构建读取 android/key.properties：

storeFile=release.keystore
storePassword=<Keystore 密码>
keyAlias=<Key 别名>
keyPassword=<Key 密码>

文件缺失时自动回退 debug 签名（仅适合本地调试）。

CI / 发布

手动触发 Android Release 工作流（workflow_dispatch）即可分架构构建并发布 APK。

触发参数

输入	说明
release_tag	发布 tag
release_name	发布名称
prerelease	是否预发布，默认 true
build_type	release 或 debug

流水线步骤

1. 检出代码，安装 Node 24 / JDK 21 / pnpm 10 / Android SDK 36 + NDK + CMake；
2. 写入 android/local.properties（sdk.dir / ndk.dir）；
3. 复制 .env.example 为 .env；
4. （仅 release）校验签名 Secrets，写出 release.keystore 与 key.properties；
5. pnpm install --frozen-lockfile → build:web → cap sync → build:android:node → prepare:android:embedded；
6. ./gradlew assembleRelease 或 assembleDebug；
7. 收集各 ABI 的 APK，重命名为 SFA-{build_type}-{version}-{abi}.apk 并生成 .sha256；
8. 上传 artifact 并创建 GitHub Release。

debug 构建不需要任何签名 Secrets。

签名 Secrets

Secret	说明
ANDROID_KEYSTORE_BASE64	Keystore 的 Base64 编码
ANDROID_KEYSTORE_PASSWORD	Keystore 密码
ANDROID_KEY_ALIAS	Key 别名
ANDROID_KEY_PASSWORD	Key 密码

生成 Base64（PowerShell）：

[Convert]::ToBase64String([IO.File]::ReadAllBytes("release.keystore")) | Set-Clipboard

常用命令

命令	说明
pnpm build:web	构建 Web 产物
pnpm build:android	完整 Android 构建管线
pnpm api:start	本地启动独立 API 服务
pnpm lint	ESLint 检查（0 错误 0 警告）
pnpm format	Prettier 格式化
pnpm typecheck	typecheck:node + typecheck:web

仓库内没有 pnpm dev

本仓库已剥离 Electron 桌面端链路，不提供 dev 脚本。调试 Web 层可直接 pnpm build:web 后同步到设备，或使用 Android Studio 的 WebView 调试（需自行开启 webContentsDebuggingEnabled）。