如何为移动 App 上线准备技术检查清单

如何为移动 App 上线准备一份技术检查清单？ 准备一份移动 App 上线技术检查清单，需要验证 Universal Links 和 App Links 的域名关联性，审计 AASA 文件和 assetlinks.json 文件，校验 SDK 初始化流程，并在提交应用商店前通过真实设备对参数路由进行测试。

App 上线检查清单是一套系统性的上线前技术审计协议，旨在正式发布前验证关键的移动基础设施，包括深度链接（Deep Link）域名、归因 SDK 生命周期以及参数还原链路。通过系统化的飞行前测试，工程团队能够及早发现上线后的导航风险、归因集成缺陷以及发布准备度问题，避免商业发布受到影响。

为什么发布前进行深度链接验证能保护 App 上线的 ROI？

应用商店发布失败的商业成本：为何审批通过后的返工会阻碍增长

公开发布 App 是软件交付过程中至关重要的时刻。一旦二进制包通过 App Store 审核或 Google Play 的自动安全检查进入生产环境，深度链接或归因基础设施的技术疏漏就可能引发严重的商业瓶颈。如果营销活动开始分发追踪链接，而底层的域名关联配置却失效，用户点击后将跳转至通用页面或 404 错误页面，而非预期的精准推广页面。

原生配置缺陷（如 Associated Domains 权限配置错误或二进制包中的包名声明不当）通常需要重新打包、提升版本号并重新提交审核。这一流程往往耗时数个工作日，导致推广费用白白浪费，并错过发布初期的用户增长窗口。相比之下，服务器端的关联缺陷（如托管在 assetlinks.json 中的 SHA-256 签名证书指纹错误或 AASA 路径配置不当）通常无需重新打包，仅需在服务端修正并重新验证域名即可解决。

发布前架构：将客户端代码签名与域名验证解耦

一套稳健的发布前验证策略应将客户端二进制包的编译与服务端的域名验证分离。编译过程确定了原生路由逻辑和 SDK 钩子，而操作系统通过获取指定 HTTPS 域名下的外部 JSON 声明来确认目标的权威性。

在向商店后台上传最终版本前，确保服务器托管的声明文件与本地二进制配置一致，可以保证安装后 App 与网站的验证成功。OpenInstall 作为独立的移动增长与归因平台，提供了相应的测试流程，助力发布团队在上线前于暂存环境中验证参数传递与域名映射情况。

设定软发布与正式发布阶段的发布阈值

发布工程框架在代码晋升前要求确定的质量门禁。当涉及到基于 web-to-app 的深度链接场景时，App 的上线高度依赖于已通过验证的 Universal Links 和 App Links。团队在执行分阶段发布或区域性软发布时，应对测试版本实施严格的标准：

• 域名验证门禁：通过命令行查询自动验证生产和暂存环境的域名关联端点。
• 冷启动参数还原门禁：模拟商店跳转流程，在纯净的物理测试设备上验证参数恢复能力。
• 容错保护门禁：当路由字符串格式错误、过期或被篡改时，确认能够平滑降级至应用首页或 Web 落地页。

如何在提交 App 前审计 iOS Universal Links 和 AASA 托管配置

校验 apple-app-site-association JSON 格式及 HTTPS 响应头

iOS Universal Links 要求目标域名安全托管一个 apple-app-site-association (AASA) JSON 文件。操作系统会查询该文件以识别哪些 URL 路径应触发应用原生执行，而非默认的 Safari 浏览会话。

AASA 文件必须存放于 https://<domain>/.well-known/apple-app-site-association 或 https://<domain>/apple-app-site-association。发布前审计必须验证 HTTP 响应头和 JSON 主体的有效性：

curl -I https://app.example.com/.well-known/apple-app-site-association
curl -fsS https://app.example.com/.well-known/apple-app-site-association | jq .

首条命令必须返回 200 OK 状态码且不应跟随重定向（HTTP 301 或 302 重定向会导致 iOS 关联验证失败）。服务器必须通过有效的 HTTPS 连接提供负载，且 header 必须包含 Content-Type: application/json。

JSON 负载必须严格遵守 Apple 的现代架构规范，不得错误地封装数组：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": [ "TEAMID1234.com.example.app" ],
        "components": [
          {
            "/": "/open/*",
            "?": { "promo": "?*" },
            "comment": "匹配推广营销活动路由"
          },
          {
            "/": "/help",
            "exclude": true,
            "comment": "保留 Web 端的帮助文档路由"
          }
        ]
      }
    ]
  }
}

通过开发者模式权限绕过 Apple CDN 缓存延迟

在 iOS 14 及更高版本中，Apple 的 CDN 会获取并缓存 AASA 文件。Apple 官方未发布固定的 48 小时传播保证，且无直接的 CDN 无效化控制手段。设备会定期检查更新；根据 Apple 的技术指南，已安装的应用每周大约检查一次，而重新安装应用可以触发更新后的关联记录检索。

仅用于开发测试时，团队可以在 Associated Domains 授权中添加 ?mode=developer，在设备设置中开启开发者模式和 Associated Domains Development，并使用开发预置配置文件签名的版本进行测试：

<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:app.example.com?mode=developer</string>
</array>

由于此模式需要开发签名，因此它仅作为开发诊断工具，而非 TestFlight 或生产环境的验证方式。

使用 macOS 命令行工具审计二进制包权限

在向 TestFlight 或 App Store Connect 上传存档前，请验证 Xcode 在编译过程中是否正确嵌入了预期的 Associated Domains 权限：

codesign -d --entitlements :- /path/to/Payload/YourApp.app

检查 XML 输出以确认 com.apple.developer.associated-domains 键存在，且无格式错误或多余空格，并包含预期的生产主机字符串。

通过 Apple CDN 查询验证 AASA 的 CDN 传播状态

在将版本晋升至正式生产环境前，查询 Apple 的公共边缘缓存，以验证 CDN 是否已成功抓取并校验了服务器端的 AASA 记录：

curl -v https://app-site-association.cdn-apple.com/a/v1/app.example.com

匹配的 CDN 响应是重要的诊断信号，但不能视为 Universal Link 在每台设备上行为的绝对保证。在诊断发布准备度时，请务必确认设备端的关联状态。

如何通过 CLI 验证 Android App Links 和域名关联

使用生产环境发布密钥库指纹构建 assetlinks.json

Android App Links 要求托管一份数字资产链接声明文件，位于 https://<domain>/.well-known/assetlinks.json。该声明告知 Android 操作系统，指定移动包已获得开启特定网页链接的授权。

assetlinks.json 文件必须包含用于对目标二进制包签名的密钥库的准确 SHA-256 证书指纹：

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": [
        "14:6D:E9:DE:0F:70:FF:E5:43:7E:0E:36:4F:18:28:4F:73:EC:82:E6:31:43:18:B3:3E:E6:2B:6A:BD:EF:94:3E"
      ]
    }
  }
]

若要从现有发布密钥库中提取生产指纹，请执行 Java keytool 工具：

keytool -list -v -keystore /path/to/release.keystore -alias release_key

如果通过 Google Play App Signing 进行部署，请确保在 assetlinks.json 中声明的指纹与 Google Play 管理中心列出的应用签名密钥证书匹配，而非本地上传密钥。

配置 Intent Filter：将验证后的 HTTPS App Links 与自定义 Scheme 隔离

根据 Android App Links Intent Filter 添加开发指南，Manifest 文件应将已验证的 App Link 过滤器与自定义 Scheme 降级方案隔离开来。在 autoVerify="true" 过滤器块中混合自定义 Scheme 声明可能会破坏 Android 各版本的主机验证。

<!-- AndroidManifest.xml: 已验证的 App Link Intent Filter -->
<intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="http" />
    <data android:scheme="https" />
    <data android:host="app.example.com" />
</intent-filter>

<!-- 用于自定义降级 Scheme 的独立 Intent Filter -->
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="yourapp" />
</intent-filter>

使用 Android 调试桥 (ADB) 执行自动化域名验证诊断

在本地安装候选发布版本后，通过 Android 调试桥 (ADB) 触发手动域名验证以确认结果：

adb shell pm set-app-links --package com.example.app 0 all
adb shell pm verify-app-links --re-verify com.example.app

给验证程序足够的时间完成网络请求，然后查询验证子系统状态以确认域名批准情况：

adb shell pm get-app-links com.example.app

终端输出必须显示已验证状态：

com.example.app:
    ID: 01234567-89ab-cdef-0123-456789abcdef
    Signatures: [14:6D:E9:DE:0F:70:FF:E5:43:7E:0E:36...]
    Domain verification state:
      app.example.com: verified

处理 Android 12 及更高版本的更新域名验证状态

在 Android 12 及以上版本中，已声明的主机被独立评估。如果一个域名成功验证，即使另一个已声明的主机验证失败，应用也能作为该已验证主机的默认链接处理器。相比之下，在 Android 11 及更低版本中，域名验证是“全有或全无”的：只要有任何一个声明主机验证失败，该过滤器块下的所有主机都可能无法完成自动链接验证。参考 Android App Links 故障排除指南有助于识别签名不匹配、重定向循环或网络可达性障碍。

端到端测试协议：参数传递与场景还原

“热启动”深度链接唤起与“延迟”参数还原的关键区别

发布前验证必须区分两种主要的深度链接生命周期状态：

• 直接唤起 (热启动)：应用已在测试设备上安装。点击 Universal Link 或 App Link 会直接启动或恢复应用进程，通过原生 Intent 或用户活动代理传递查询参数。
• 延迟参数还原 (安装后的冷启动)：应用尚未安装。点击链接会打开网页路由落地页，保留上下文，重定向至商店，并在 App 首次启动时还原动态参数。

验证 SDK 早期初始化而不阻塞主线程

归因与深度链接 SDK 必须在应用生命周期的早期进行初始化，以注册传入的 Intent 钩子。在 Android 架构中，初始化应在 Application.onCreate() 回调中完成，并防止多进程重复初始化。在 iOS 环境中，配置则应归属于 application(_:didFinishLaunchingWithOptions:)。

虽然初始注册钩子会在应用启动时执行，但繁重的计算和阻塞性网络 I/O 必须从 Android 主 UI 线程中剥离，以防止应用无响应 (ANR) 警告。

以下技术实现展示了跨原生 Android (Kotlin) 和 iOS (Swift) 架构的结构化预发布验证逻辑。开发者可查阅 SDK 集成文档了解各框架的特定生命周期规范。

// Android: MainActivity.kt - 预发布 Intent 日志记录与路由诊断
package com.example.app

import android.content.Intent
import android.net.Uri
import android.os.Bundle
import android.util.Log
import androidx.appcompat.app.AppCompatActivity
import com.opoinstall.api.OpoInstall
import com.opoinstall.api.listener.AppWakeUpAdapter
import com.opoinstall.api.model.AppData
import org.json.JSONObject

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // 审计传入的冷启动 Intent
        auditLaunchIntent(intent, "onCreate")
        processDeepLink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        setIntent(intent)

        // 审计热启动恢复 Intent
        auditLaunchIntent(intent, "onNewIntent")
        processDeepLink(intent)
    }

    private fun processDeepLink(intent: Intent?) {
        if (intent == null) return

        OpoInstall.getInstance().getWakeUp(intent, object : AppWakeUpAdapter() {
            override fun onWakeUp(appData: AppData?) {
                if (appData == null) {
                    Log.d(TAG, "未解析到深度链接参数。")
                    return
                }

                val channel = appData.channelCode ?: "organic"
                val customData = appData.data ?: "{}"

                Log.i(TAG, "预发布路由已验证 - 渠道: $channel, 参数: $customData")

                // 步骤 1: 输入清洗、类型约束与路由验证
                val validatedRoute = validateRoutePayload(customData)
                if (validatedRoute != null) {
                    // 步骤 2: 使用 App 已认证的会话授权后端服务
                    authorizeRoute(validatedRoute) { isAuthorized ->
                        runOnUiThread {
                            if (isAuthorized) {
                                executeTargetNavigation(validatedRoute)
                            } else {
                                executeLobbyFallback("路由未授权、已过期或不可用。")
                            }
                        }
                    }
                } else {
                    runOnUiThread {
                        executeLobbyFallback("路由参数格式错误或无法验证。")
                    }
                }
            }
        })
    }

    private fun validateRoutePayload(rawJson: String): ValidatedRoute? {
        return try {
            val json = JSONObject(rawJson)
            val scene = json.optString("scene", "")
            val targetId = json.optString("target_id", "")

            // 校验场景是否在白名单内
            val allowedScenes = setOf("event_hub", "promo_detail", "guild_hall")
            if (!allowedScenes.contains(scene)) {
                return null
            }

            // 对目标 ID 强制执行长度和字符白名单约束
            if (targetId.isBlank() || targetId.length > 128 || !targetId.matches(Regex("^[A-Za-z0-9_-]+$"))) {
                return null
            }

            ValidatedRoute(scene, targetId)
        } catch (e: Exception) {
            Log.e(TAG, "JSON 参数验证失败", e)
            null
        }
    }

    private fun authorizeRoute(route: ValidatedRoute, callback: (Boolean) -> Unit) {
        // 已认证的会话由应用会话状态提供；URL 提供路由上下文
        BackendRouteAuthorizer.verifyRouteAuthorization(route.scene, route.targetId) { result ->
            callback(result.isAuthorized && result.isResourceAvailable)
        }
    }

    private fun executeTargetNavigation(route: ValidatedRoute) {
        Log.i(TAG, "正在导航至已验证场景: ${route.scene}, ID: ${route.targetId}")
        // 执行内部导航路由至目标场景
    }

    private fun executeLobbyFallback(reason: String) {
        Log.w(TAG, "执行安全大厅降级: $reason")
        // 安全导航至默认大厅
    }

    private fun auditLaunchIntent(intent: Intent?, lifecycleStage: String) {
        val action = intent?.action
        val data: Uri? = intent?.data
        Log.d(TAG, "[$lifecycleStage] Action: $action, Data URI: $data")
    }

    data class ValidatedRoute(val scene: String, val targetId: String)

    companion object {
        private const val TAG = "PreFlightAudit"
    }
}

// iOS: AppDelegate.swift - 预发布 Universal Link 审计与日志记录
import UIKit
import libOpoInstallSDK

@main
class AppDelegate: UIResponder, UIApplicationDelegate, OpoInstallDelegate {

    var window: UIWindow?

    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        // 早期初始化 OpoInstall SDK，且不阻塞主线程
        OpoInstallSDK.initWith(self)
        return true
    }

    // 处理传入的 Universal Links
    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb, let webpageURL = userActivity.webpageURL {
            NSLog("[PreFlightAudit] 接收到的 Universal Link URL: %@", webpageURL.absoluteString)
        }

        // 将解析代理给 OpoInstall SDK
        OpoInstallSDK.continue(userActivity)
        return true
    }

    // 唤起回调处理
    func getWakeUpParams(_ appData: OpoInstallData?) {
        guard let data = appData else {
            NSLog("[PreFlightAudit] 未还原动态参数。")
            return
        }

        let channel = data.channelCode ?? "organic"
        let payload = data.data ?? "{}"

        NSLog("[PreFlightAudit] Universal Link 已验证 - 渠道: %@, 参数: %@", channel, payload)

        // 步骤 1: 输入清洗、长度检查与白名单校验
        if let validatedRoute = validateRoutePayload(payload) {
            // 步骤 2: 使用 App 已认证的会话授权后端服务
            authorizeRoute(route: validatedRoute) { isAuthorized in
                DispatchQueue.main.async {
                    if isAuthorized {
                        self.navigateToScene(route: validatedRoute)
                    } else {
                        self.navigateToLobbyFallback(reason: "路由未授权、已过期或不可用。")
                    }
                }
            }
        } else {
            DispatchQueue.main.async {
                self.navigateToLobbyFallback(reason: "参数验证失败或目标已过期")
            }
        }
    }

    private func validateRoutePayload(_ rawJson: String) -> (scene: String, targetId: String)? {
        guard let data = rawJson.data(using: .utf8) else { return nil }

        do {
            if let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
                let scene = json["scene"] as? String ?? ""
                let targetId = json["target_id"] as? String ?? ""

                // 校验场景是否在白名单内
                let allowedScenes = ["event_hub", "promo_detail", "guild_hall"]
                guard allowedScenes.contains(scene) else { return nil }

                // 对目标 ID 强制执行长度和字符集约束
                let validCharacters = CharacterSet(charactersIn: "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-_")
                guard !targetId.isEmpty,
                      targetId.count <= 128,
                      targetId.rangeOfCharacter(from: validCharacters.inverted) == nil else {
                    return nil
                }

                return (scene: scene, targetId: targetId)
            }
        } catch {
            NSLog("[PreFlightAudit] 反序列化 JSON 路由参数失败: %@", error.localizedDescription)
        }
        return nil
    }

    private func authorizeRoute(route: (scene: String, targetId: String), completion: @escaping (Bool) -> Void) {
        // 已认证的会话由应用会话状态提供；URL 提供路由上下文
        BackendRouteAuthorizer.shared.verifyRouteAuthorization(scene: route.scene, targetId: route.targetId) { result in
            completion(result.isAuthorized && result.isResourceAvailable)
        }
    }

    private func navigateToScene(route: (scene: String, targetId: String)) {
        NSLog("[PreFlightAudit] 正在导航至已验证场景: %@, ID: %@", route.scene, route.targetId)
        // 执行内部导航路由至目标场景
    }

    private func navigateToLobbyFallback(reason: String) {
        NSLog("[PreFlightAudit] 导航至安全大厅降级: %@", reason)
        // 安全导航至默认大厅
    }
}

验证输入清洗与异常或过期参数的降级方案

由于 URL 查询字符串和深度链接参数源自外部 Web 环境，应用必须将传入的参数视为非信任输入。验证套件必须确保：

• 缺失或为空的查询字符串不会在初始化期间产生空指针异常或导致应用崩溃。
• 路由参数强制执行严格的数据类型解析、字符白名单过滤和长度限制。
• 服务器授权在场景执行前校验目标资源状态和会话有效性，若已过期或未授权则触发安全降级。

在真实物理设备上自动化上线前健康检查

为何必须辅以物理设备验证

仅在软件模拟器上测试深度链接和参数还原会引入显著的误报风险。模拟器共享宿主机操作系统的剪贴板，缺乏运营商特定的网络带宽限制，且无法模拟特定厂商的电池优化服务，这些服务可能会延迟 SDK 的后台任务。

发布前验证应在涵盖多个操作系统版本和不同原始设备制造商 (OEM) 环境的物理硬件上进行。

测试分阶段下载流程：利用参数化二维码进行内部验证

为验证延迟深度链接（Deferred Deep Linking），发布团队应部署一套双阶段验证框架，测试本地逻辑及商店分发链路：

1. 本地安装模拟：直接将签名后的开发或 Ad-hoc 版本侧载至纯净的物理设备上，验证 SDK 回调、文档化的延迟匹配前提条件，以及在无商店干扰下的参数还原效果。
2. 商店分发验证：将候选发布版本部署至正式的发布前渠道——iOS 的 TestFlight 和 Android 的内部或封闭测试渠道。扫描测试二维码 (https://app.example.com/join?channelCode=QA_PreRelease&inviteCode=TEST_USER_99)，走完商店下载路径，并验证已安装应用在首次启动时是否能准确还原参数。

模拟冷启动、进程重启与后台恢复状态

完整的验证要求在各种进程条件下对状态还原进行确认：

• 冷启动：在进程已完全从设备内存中终止的情况下，通过 Universal Link 启动 App。
• 热启动：在进程于后台挂起的情况下，通过链接启动 App，确认 onNewIntent 或 continueUserActivity 能成功捕获事件。
• 内存压力清理：挂起 App，通过开发者选项模拟系统内存压力终止后台进程，验证 App 重新启动后，深度链接状态能按预期还原。

[配置发布版本]
              │
              ▼
[平台关联审计]
   ┌──────────┴──────────┐
   ▼                     ▼
[iOS AASA 检查]    [Android DAL 检查]
   │                     │
   ▼                     ▼
[Apple CDN 查询]   [ADB App-Link 检查]
   │                     │
   └──────────┬──────────┘
              ▼
[纯净设备沙箱安装]
              │
              ▼
[参数化链接 & 二维码扫描]
              │
              ▼
[SDK 参数还原 & 校验]
   ┌──────────┴──────────┐
   ▼                     ▼
[加载目标场景]   [触发安全降级]
              │
              ▼
[批准正式上线]

上线前技术验证与故障缓解矩阵

全面的飞行前技术审计清单

下表总结了基础设施的主要验证节点、相关的命令行诊断工具以及策略性缓解协议：

总结与决策框架

成功的移动 App 上线依赖于结构化的发布前技术执行。忽视域名验证配置或参数还原工作流，可能会破坏营销活动并降低用户初期的 onboarding 体验。

通过系统地执行命令行诊断、审计 Apple CDN 传播情况以及在物理硬件上校验延迟参数流，工程团队可以减少上线日的盲点。集成经开发者测试的工具，有助于在正式发布前验证深度链接与归因管道的行为是否可预测。

欲了解如何配置与验证上线前的深度链接工作流，请查阅 SDK 集成文档，探索 OpenInstall SDK 下载中心，查看 GitHub 上的开源示例，或在 OpenInstall 开发者控制台配置您的测试应用。

相关资料

• 概念: App 上线清单, 飞行前验证, 场景还原, Apple CDN 无效化, 数字资产链接

• 技术: Universal Links, Android App Links, 延迟深度链接, 关联域 (Associated Domains)

• 标准: IETF RFC 3986 统一资源标识符, Apple Associated Domains 授权规范, Android 数字资产链接协议, OWASP 移动应用安全测试指南 (MASTG)

• API: OpenInstall SDK 初始化 API, Android Intent Filter 验证 API, iOS NSUserActivity 路由接口

• 官方文档与参考:

  • Apple 关于支持关联域的开发者文档

  • Apple 关于调试 Universal Links 的技术说明 TN3155

  • Android 关于验证 App Links 的开发者指南

  • Android 关于 App Links 故障排除的开发者指南

  • OWASP 移动应用安全测试指南：不安全的深度链接

  • OpenInstall GitHub 开源集成示例