企业官网建设流程全解析

一个名为 Vellum 的开源移动应用完成双端上线后，很多人只看到“开源”和“上线”这两个结果，却容易忽略中间那条完整工程链路：仓库怎么组织、许可证怎么选、代码如何同时构建出 iOS 与 Android 产物、签名和证书怎么交接、商店审核要准备什么材料、发布之后又靠什么监控崩溃和收集反馈。本文以这个场景为主线，把开源 iOS/Android 应用从代码到上线的完整过程拆开讲清楚。

这篇文章适合三类读者：准备把个人项目开源并上架到应用商店的独立开发者；团队里负责移动端交付、CI/CD 或发版流程的工程师；以及刚开始接触双端开发，想知道一份工程到底要经过哪些环节才能进入生产环境的新人。看完后，你会得到一条可以照着执行的上线路径，也知道每一环出问题时应该往哪里查。

1. 理解开源双端上线的完整技术链路

1.1 上线不是“代码能跑”，而是“工程可交付”

在开发环境里，能跑通一个界面、能调通一个接口，只代表业务代码基本成型。真正进入上线阶段时，面对的是一组完全不同的约束。

首先是构建的可重复性。今天在本地能编译出 IPA，不代表下周换一台机器、换一个 JDK、换一个 Xcode 版本还能编译出相同产物。开源项目最大的特点是协作方多，如果依赖没有锁定，任何一位贡献者都可能因为版本漂移而构建失败。

其次是签名和分发。iOS 的 App Store、Android 的应用商店都要求正式签名。签名不仅是身份的证明，还关系到后续的版本升级、推送、崩溃堆栈还原。签名体系一旦配置错误，轻则构建失败，重则线上无法升级。

再次是审核和合规。商店审核关注功能完整性、隐私政策、权限使用说明、内容安全等多个维度。开源项目往往因为“没有隐私政策页面”“权限弹窗没写用途”这类问题被拒，而不是因为功能不够多。

所以，开源双端上线的完整技术链路至少包含八段：仓库与许可证、工程结构、环境依赖、构建、签名、商店发布、监控、迭代。每一段都要有可执行、可验证、可回滚的方案。

1.2 学习环境与生产环境的七个差异

同一个开源项目，在个人学习环境里可以直接用 debug 签名、连测试接口、在模拟器里跑；正式上线时必须切换成另一套配置。下面这张表总结了最常见的差异。

区分这两类环境不是小题大做。很多上线事故都源于开发环境配置被带到了生产环境：接口指向测试服、debug 日志全量输出、密钥写在代码里。开源项目因为仓库公开，这类问题的影响范围比内部项目更大。

1.3 iOS 与 Android 的发布差异决定了流水线形态

开源项目同时支持两端，意味着要同时维护两条分发链路。它们的核心逻辑相似，但具体机制差异很大。

实际操作中，两条流水线会共享一套代码仓库、一份版本号规划、一套发布检查清单，但构建步骤、签名步骤和上传步骤必须分开写。建议从一开始就确认 CI 的 runner 配置：Android 构建可以用 Linux runner，iOS 构建必须使用 macOS runner。

2. 仓库、许可证与工程结构

2.1 开源仓库必须先定许可证

开源不是“把代码传到 GitHub 上”那么简单的动作。没有 LICENSE 文件的仓库，在法律上默认保留所有权利，别人即使看到代码也不能合法使用、修改或分发。这个状态对项目发展非常不利。

移动应用客户端常用的开源许可证有三种，选型时要考虑项目定位。

对于 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 的组合。

AGP（Android Gradle Plugin）、Gradle 和 JDK 三个版本必须匹配。这是 Android 新手最容易踩的坑，经常可以看到类似“android studio hedgehog 版本支持 AGP 8 吗”这类问题。这类问题本质上是版本矩阵的匹配问题。

安装 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/export

ExportOptions.plist 示例：

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>method</key> <string>app-store</string> <key>teamID</key> <string>TEAMID123</string> <key>uploadSymbols</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 要求使用 AAB（Android 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/checkout@v4 - name: Set up JDK 17 uses: actions/setup-java@v4 with: distribution: temurin java-version: "17" - name: Setup Gradle uses: gradle/actions/setup-gradle@v3 - 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-artifact@v4 with: name: vellum-release path: app/build/outputs/bundle/release/app-release.aab

iOS 流水线类似，但 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 Store

App 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:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS 在 Info.plist 中声明用途描述。比如要访问相册，就必须写 NSPhotoLibraryUsageDescription，否则系统会直接拒绝应用运行：

<key>NSPhotoLibraryUsageDescription</key> <string>用于选择用户头像</string>

隐私政策是双端审核的必填材料。它不能只写一句“我们不收集数据”。只要接入了崩溃统计、推送、广告、社交登录这些第三方 SDK，就要在政策里列出收集了哪些数据、由哪个 SDK 处理、用于什么目的。开源项目建议把隐私政策放到 docs 目录并部署为可访问的 URL，而不是放在仓库里让人自己找。

5.4 审核被拒的处理路径

审核被拒不是终点，重点是从提示反推原因。

提交审核前，把“被拒后怎么改”当作战术动作来准备：本地保留一份完整的素材清单，包括截图、关键词、支持网址、隐私政策 URL，方便按审核意见快速修改。

5.5 灰度发布与回滚

灰度发布