一个名为 Vellum 的开源移动应用完成双端上线后很多人只看到“开源”和“上线”这两个结果却容易忽略中间那条完整工程链路仓库怎么组织、许可证怎么选、代码如何同时构建出 iOS 与 Android 产物、签名和证书怎么交接、商店审核要准备什么材料、发布之后又靠什么监控崩溃和收集反馈。本文以这个场景为主线把开源 iOS/Android 应用从代码到上线的完整过程拆开讲清楚。这篇文章适合三类读者准备把个人项目开源并上架到应用商店的独立开发者团队里负责移动端交付、CI/CD 或发版流程的工程师以及刚开始接触双端开发想知道一份工程到底要经过哪些环节才能进入生产环境的新人。看完后你会得到一条可以照着执行的上线路径也知道每一环出问题时应该往哪里查。1. 理解开源双端上线的完整技术链路1.1 上线不是“代码能跑”而是“工程可交付”在开发环境里能跑通一个界面、能调通一个接口只代表业务代码基本成型。真正进入上线阶段时面对的是一组完全不同的约束。首先是构建的可重复性。今天在本地能编译出 IPA不代表下周换一台机器、换一个 JDK、换一个 Xcode 版本还能编译出相同产物。开源项目最大的特点是协作方多如果依赖没有锁定任何一位贡献者都可能因为版本漂移而构建失败。其次是签名和分发。iOS 的 App Store、Android 的应用商店都要求正式签名。签名不仅是身份的证明还关系到后续的版本升级、推送、崩溃堆栈还原。签名体系一旦配置错误轻则构建失败重则线上无法升级。再次是审核和合规。商店审核关注功能完整性、隐私政策、权限使用说明、内容安全等多个维度。开源项目往往因为“没有隐私政策页面”“权限弹窗没写用途”这类问题被拒而不是因为功能不够多。所以开源双端上线的完整技术链路至少包含八段仓库与许可证、工程结构、环境依赖、构建、签名、商店发布、监控、迭代。每一段都要有可执行、可验证、可回滚的方案。1.2 学习环境与生产环境的七个差异同一个开源项目在个人学习环境里可以直接用 debug 签名、连测试接口、在模拟器里跑正式上线时必须切换成另一套配置。下面这张表总结了最常见的差异。环节学习/开发环境正式上线环境签名debug 证书或自动签名正式证书或独立 keystore需安全备份构建本机直接编译CI 可重复构建产物可追溯接口地址本地或测试服生产域名HTTPS错误处理完整日志控制台打印日志系统加崩溃上报权限能跑就行最小权限弹窗文案写清用途发布模拟器或真机安装商店审核、灰度、正式上架回滚重装即可版本下线、紧急修复、渠道回滚区分这两类环境不是小题大做。很多上线事故都源于开发环境配置被带到了生产环境接口指向测试服、debug 日志全量输出、密钥写在代码里。开源项目因为仓库公开这类问题的影响范围比内部项目更大。1.3 iOS 与 Android 的发布差异决定了流水线形态开源项目同时支持两端意味着要同时维护两条分发链路。它们的核心逻辑相似但具体机制差异很大。对比项iOSAndroid构建平台macOS XcodeWindows/macOS/Linux 均可签名体系证书 Provisioning Profilekeystore Gradle 签名测试渠道TestFlight 内部/外部测试内测分发或开放测试正式分发App StoreGoogle Play、国内商店、GitHub Releases审核机制有周期不稳定各渠道不同部分渠道自动审核版本回滚审核制下回滚较慢可下架上一版本或停用实际操作中两条流水线会共享一套代码仓库、一份版本号规划、一套发布检查清单但构建步骤、签名步骤和上传步骤必须分开写。建议从一开始就确认 CI 的 runner 配置Android 构建可以用 Linux runneriOS 构建必须使用 macOS runner。2. 仓库、许可证与工程结构2.1 开源仓库必须先定许可证开源不是“把代码传到 GitHub 上”那么简单的动作。没有 LICENSE 文件的仓库在法律上默认保留所有权利别人即使看到代码也不能合法使用、修改或分发。这个状态对项目发展非常不利。移动应用客户端常用的开源许可证有三种选型时要考虑项目定位。许可证商用修改后闭源分发典型场景注意事项MIT允许允许工具库、客户端模板需保留版权声明Apache-2.0允许允许偏工程化、需要专利保护的项目已修改文件通常需保留声明GPL-3.0允许不允许希望衍生代码继续开源的社区项目分发时需按同样许可证提供源码对于 Vellum 这类以移动客户端为主的开源应用MIT 和 Apache-2.0 更常见因为不会给下游集成者带来额外的许可证义务。如果项目包含图标、字体、示例图片等素材还要单独检查素材许可证是否能随项目分发。仓库创建时托管平台通常会在新建页面提供许可证选择入口如果已经创建仓库就把 LICENSE 文件放到仓库根目录。注意 LICENSE 文件里的版权所有者名称、年份要写清楚例如 Copyright (c) 2024 Vellum Contributors。2.2 单仓库还是多仓库开源项目往往不只是客户端代码还伴随后端服务、文档、设计稿、脚本等资源。这里需要做一个仓库组织决策。单仓库Monorepo适合独立开发者和小团队一次提交能同时更新文档和代码PR 上下文完整CI 配置集中管理。缺点是仓库体积增长快权限粒度粗。多仓库Multi-repo适合客户端、后端、管理后台分别发布的项目各团队独立维护、独立权限、独立发布。缺点是跨仓库改动时要同时提多个 PR版本对齐成本高。对首次上线的开源移动应用建议先走单仓库把 app、packages、docs、scripts 放在一起。等发布节奏稳定后再把后端或管理后台拆出去。2.3 目录结构设计一个同时包含 iOS 与 Android 客户端的单仓库可以参考下面这个结构。vellum/ ├── LICENSE ├── README.md ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── SECURITY.md ├── app/ │ ├── ios/ # iOS 工程入口 │ └── android/ # Android 工程入口 ├── packages/ # 双端共享的业务模块 ├── docs/ # 文档、隐私说明、架构说明 ├── scripts/ # 构建、签名、上传辅助脚本 └── .github/ └── workflows/ # 双端 CI 流水线这个结构的关键点有三个入口分离、共享模块独立、脚本和文档与代码同库。入口分离保证两端各自的构建工具链不会被互相干扰共享模块独立是为了避免业务逻辑复制两份脚本与代码同库则让整个发版流程可以版本化。2.4 社区文件不能省开源项目上线后仓库本身就是产品。除了代码还要准备好几类社区文件。README 要回答五个问题这个项目是什么、截图效果如何、怎么构建、怎么贡献、使用什么许可证。CONTRIBUTING 要说明提 Issue 和 PR 的流程、代码风格要求、测试要求。SECURITY 要提供漏洞上报渠道移动应用一旦泄露用户数据后果非常严重。CODE_OF_CONDUCT 用于约束社区讨论方式。此外Issue 模板和 PR 模板可以显著降低维护成本避免大量无效问题。CI 状态徽章建议放在 README 顶部它直接告诉贡献者“当前主干是否可构建”是开源项目可信度的基础信号。3. 环境准备与依赖锁定3.1 iOS 端环境iOS 构建必须在 macOS 上完成这是硬性约束。基础环境包括Xcode、Command Line Tools、CocoaPods 或 Swift Package Manager。Xcode 版本会直接影响 iOS SDK 版本和编译行为所以团队内要统一版本。实践中经常出现“本地 Xcode 15 编译通过CI 上 Xcode 14 报错”的情况原因往往是依赖库要求更高的 SDK。如果项目使用 CocoaPods需要把 Podfile.lock 提交到仓库它锁定了所有 Pod 的精确版本使用 Swift Package Manager 时Package.resolved 同样应该入库。iOS 签名还依赖 Apple Developer 账号、证书和 Provisioning Profile。第一次配置时建议把证书导出为 .p12妥善保管导出密码并把证书的作用说明记录到团队的 secret 管理文档里。3.2 Android 端环境Android 构建的环境要求相对灵活JDK、Android SDK、Gradle 是三个核心要素。Android Studio 只是 IDE真正负责编译的是 JDK、Gradle、AGP 的组合。AGPAndroid Gradle Plugin、Gradle 和 JDK 三个版本必须匹配。这是 Android 新手最容易踩的坑经常可以看到类似“android studio hedgehog 版本支持 AGP 8 吗”这类问题。这类问题本质上是版本矩阵的匹配问题。AGP 版本最低 Gradle 版本建议 JDK 版本7.47.511 或 178.28.2178.38.417安装 Android Studio 时不同版本自带不同 AGP 模板但项目最终使用哪个 AGP 由工程配置决定。推荐使用 Gradle Wrapper 固定 Gradle 版本这样任何贡献者执行 ./gradlew 时都会下载指定版本避免“我这能编译你那不行”的问题。3.3 用锁文件和版本目录固定依赖Android 工程推荐使用 Gradle Version Catalog。它把依赖版本集中在一个 TOML 文件里方便升级和统一管理。[versions] agp 8.3.2 kotlin 1.9.22 coreKtx 1.13.1 [libraries] androidx-core-ktx { module androidx.core:core-ktx, version.ref coreKtx } [plugins] android-application { id com.android.application, version.ref agp } kotlin-android { id org.jetbrains.kotlin.android, version.ref kotlin }模块的 build.gradle.kts 中通过别名引用例如plugins { alias(libs.plugins.android.application) alias(libs.plugins.kotlin.android) } dependencies { implementation(libs.androidx.core.ktx) }这样做的收益不是写起来更短而是让“升级依赖版本”变成一个可审查的变更。升级某个库之后PR 里只改一处diff 清晰可见。3.4 环境检查清单无论本机还是 CI构建前按下面顺序检查一遍。Xcode 版本与团队约定一致Command Line Tools 已安装。项目使用 Gradle Wrapper且 gradle-wrapper.properties 已提交。JDK 版本满足 AGP 要求多 JDK 环境下确认 JAVA_HOME 指向正确。Android SDK Platform 与 Build Tools 版本与 compileSdk 匹配。Podfile.lock 或 Package.resolved 已提交不依赖“我本地装过某个版本”。CI runner 的系统版本、缓存策略与本地环境对齐。4. 构建与签名上线前最容易出问题的环节4.1 iOS 签名与导出iOS 的签名体系由三层组成开发者账号、证书、Provisioning Profile。证书用来证明“你是谁”Profile 用来声明“这个 App 能装到哪些设备、能使用哪些能力”。开发阶段可以使用 Xcode 的 Automatic Signing由 Xcode 自动创建证书和 Profile。正式发布时推荐改用手动签名并在本地归档后用 exportOptionsPlist 导出 IPA。xcodebuild -workspace Vellum.xcworkspace \ -scheme Vellum \ -configuration Release \ -archivePath build/Vellum.xcarchive archive xcodebuild -exportArchive \ -archivePath build/Vellum.xcarchive \ -exportOptionsPlist ExportOptions.plist \ -exportPath build/exportExportOptions.plist 示例?xml version1.0 encodingUTF-8? !DOCTYPE plist PUBLIC -//Apple//DTD PLIST 1.0//EN http://www.apple.com/DTDs/PropertyList-1.0.dtd plist version1.0 dict keymethod/key stringapp-store/string keyteamID/key stringTEAMID123/string keyuploadSymbols/key true/ /dict /plist这里最容易出现的错误是证书和 Profile 不匹配。导出时报 “Provisioning profile does not include signing certificate” 时先检查 Profile 里包含的证书是否就是当前钥匙串里用来签名的证书再看 bundle id 是否一致。4.2 Android 签名与产物Android 正式签名使用 keystore 文件。首次生成时建议把有效期设置得足够长比如 25 年因为应用一旦发布升级包基本都要求使用同一把密钥签名。keytool -genkeypair -v \ -keystore vellum-release.keystore \ -alias vellum \ -keyalg RSA \ -keysize 2048 \ -validity 36500生成后把 keystore 文件放到安全位置密码不要写进仓库。Gradle 配置里通过环境变量读取密钥信息避免把敏感信息提交到 Git。android { signingConfigs { create(release) { storeFile file(System.getenv(KEYSTORE_FILE) ?: release.keystore) storePassword System.getenv(KEYSTORE_PASSWORD) keyAlias System.getenv(KEY_ALIAS) keyPassword System.getenv(KEY_PASSWORD) } } buildTypes { getByName(release) { signingConfig signingConfigs.getByName(release) isMinifyEnabled true proguardFiles( getDefaultProguardFile(proguard-android-optimize.txt), proguard-rules.pro ) } } }发布后可以用 apksigner 验证签名信息。apksigner 位于 Android SDK 的 build-tools 目录下。$ANDROID_HOME/build-tools/version/apksigner verify --print-certs app-release.apk正常情况下输出中包含 Signer #1 certificate DN 和证书指纹。如果输出 “DOES NOT VERIFY” 或提示证书过期说明签名有问题需要重新构建。关于分发格式Google Play 要求使用 AABAndroid App Bundle由 Play 根据设备配置生成 APK国内渠道和 GitHub Releases 通常直接分发 APK。无论哪种格式正式签名都不可省略。4.3 用 CI 让双端构建可重复构建和签名流程一旦能通过脚本完成就应该交给 CI。以 GitHub Actions 为例Android 端可以在打 tag 时自动构建 release AAB。name: build-android-release on: push: tags: - v* workflow_dispatch: jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Set up JDK 17 uses: actions/setup-javav4 with: distribution: temurin java-version: 17 - name: Setup Gradle uses: gradle/actions/setup-gradlev3 - name: Build release AAB run: ./gradlew bundleRelease env: KEYSTORE_PASSWORD: ${{ secrets.KEYSTORE_PASSWORD }} KEY_ALIAS: ${{ secrets.KEY_ALIAS }} KEY_PASSWORD: ${{ secrets.KEY_PASSWORD }} - name: Upload AAB uses: actions/upload-artifactv4 with: name: vellum-release path: app/build/outputs/bundle/release/app-release.aabiOS 流水线类似但 runs-on 必须改为 macos-14 这类 macOS runner同时需要把证书 p12、profile 文件、导出密码放入 GitHub Secrets。密钥通过 CI 上传到商店这一步可以在发布节奏稳定后再做自动化首发阶段先用 artifact 下载后手工上传风险更小。注意正式证书和密钥一旦丢失补办周期很长。发布前先在离线环境对 keystore、p12、Provisioning Profile 做备份并记录备份时间、备份位置、谁有访问权限。4.4 版本号与 Git Tag 对齐iOS 用 CFBundleShortVersionString 表示版本号、CFBundleVersion 表示构建号Android 用 versionName 表示版本号、versionCode 表示构建号。建议遵循两个规则versionCode 和 CFBundleVersion 单调递增同一个值不能重复用于两个包版本号与 Git tag 一一对应例如 v1.0.0 对应版本号 1.0.0、构建号 1。这样线上用户反馈“1.0.0 (3) 崩溃”时可以直接定位到对应的提交。5. 应用商店发布与隐私合规5.1 iOS 通过 TestFlight 到 App StoreApp Store 的常规流程是在 App Store Connect 创建应用记录上传 IPA填写版本信息和审核备注提交审核。TestFlight 是审核前的关键关卡。TestFlight 的两种测试方式值得区分Internal Testing 最多可邀请 100 名团队成员无需审核External Testing 需要提交 Beta App 审核适合小范围公开测试。外部测试最好覆盖登录、权限弹窗、深链接、升级这四个高风险路径因为审核被拒最常见的原因就是“打开后崩溃”和“功能体验不完整”。App Store 审核周期存在不确定性所以版本发布时间要预留缓冲。计划“周五发布”时至少要提前一周提交审核。5.2 Android 的 Play 与国内渠道Android 发布渠道比 iOS 多先要决定主渠道。Google Play 是海外主渠道需要配置应用签名并注意 Play App Signing 的密钥备份机制。国内安卓应用商店通常还会要求提供软件著作权、安全评估报告等材料具体以各平台当时的规定为准。对开源项目来说GitHub Releases 也是一个重要分发渠道。它成本最低适合让开发者在审核等待期间直接安装体验。发布 Release 时建议附上 AAB 或 APK 文件、SHA-256 校验值、版本说明避免用户下载到被篡改的包。5.3 权限、隐私政策与审核材料移动应用权限是审核重点。原则是“最小权限”只申请当前功能真正需要的权限并在弹窗文案里写清用途。Android 在 AndroidManifest.xml 中声明权限uses-permission android:nameandroid.permission.INTERNET / uses-permission android:nameandroid.permission.ACCESS_NETWORK_STATE /iOS 在 Info.plist 中声明用途描述。比如要访问相册就必须写 NSPhotoLibraryUsageDescription否则系统会直接拒绝应用运行keyNSPhotoLibraryUsageDescription/key string用于选择用户头像/string隐私政策是双端审核的必填材料。它不能只写一句“我们不收集数据”。只要接入了崩溃统计、推送、广告、社交登录这些第三方 SDK就要在政策里列出收集了哪些数据、由哪个 SDK 处理、用于什么目的。开源项目建议把隐私政策放到 docs 目录并部署为可访问的 URL而不是放在仓库里让人自己找。5.4 审核被拒的处理路径审核被拒不是终点重点是从提示反推原因。被拒提示常见原因处理方式缺少隐私政策未配置 URL或页面无法访问部署隐私政策页面并重新提交权限描述不清晰弹窗文案只写“需要权限”写明采集目的和使用范围崩溃或卡死测试覆盖不足先用 TestFlight 或内测跑完整流程功能不完整或占位提交了未完成版本补全核心流程或在审核备注中说明元数据不一致截图、描述与功能不符重新截图并核对关键词提交审核前把“被拒后怎么改”当作战术动作来准备本地保留一份完整的素材清单包括截图、关键词、支持网址、隐私政策 URL方便按审核意见快速修改。5.5 灰度发布与回滚灰度发布