# iOS Universal Links 配置指南：从 Apple App Site Association 到 Microsoft 365 集成实践

**作者：吉祥法师**

在现代移动应用生态系统中，通用链接（Universal Links）已成为连接 Web 内容与原生应用体验的核心桥梁。这项由 Apple 引入的技术，使得 iOS 设备能够在不经过 Safari 浏览器中转的情况下，直接从网页链接跳转到对应的原生应用页面，实现无缝的用户体验。然而，通用链接的配置并非简单的开关设置，它涉及 Apple App Site Association（AASA）文件的准确部署、多个应用的协调配置、以及服务器端与客户端的精确匹配。本文将深入解析通用链接的工作原理，并以 Microsoft 365 系列的通用链接配置清单为实例，详细阐述从理论到实践的完整配置流程。

## 一、通用链接的核心概念与工作原理

### 1.1 什么是通用链接

通用链接是 Apple 在 iOS 9 中引入的一项深度链接技术，它允许开发者将一个标准的 HTTP 或 HTTPS 链接映射到原生应用中的特定页面。当用户点击这类链接时，如果设备上已安装对应的应用，系统会直接打开应用并跳转到指定内容；如果未安装应用，则会回退到浏览器中加载该 URL 的 Web 页面。这种“二象性”使得通用链接成为连接 Web 与 App 的最佳实践方案。

### 1.2 核心工作原理

通用链接的实现依赖三个关键要素：

- **Apple App Site Association 文件**：这是一个位于网站根目录下的 JSON 文件，用于声明哪些应用可以处理特定路径下的链接。系统通过 HTTPS 协议访问该文件来验证关联关系。

- **应用标识符**：每个 iOS 应用都有一个唯一的团队标识符（Team ID）和应用标识符（Bundle ID），AASA 文件中需要明确列出这些标识符以建立信任关系。

- **路径匹配规则**：AASA 文件中的路径声明定义了应用可以处理的 URL 模式。系统会根据这些规则决定是否触发应用跳转。

### 1.3 与传统 URL Scheme 的区别

传统 URL Scheme（如 `myapp://page`）虽然也能实现应用跳转，但存在明显缺陷：

- **冲突风险**：多个应用可能注册相同的 Scheme，导致系统无法确定由哪个应用处理。
- **安全漏洞**：恶意应用可以劫持合法的 Scheme。
- **用户体验差**：未安装应用时，点击链接只会显示错误提示，无法回退到网页。

通用链接通过 HTTPS 验证机制解决了上述问题，因为只有网站所有者才能修改 AASA 文件，从而确保链接的真实性和安全性。

## 二、AASA 文件的配置规范与详细解析

### 2.1 文件结构概述

AASA 文件是一个 JSON 格式的配置文件，通常命名为 `apple-app-site-association`（注意没有 .json 后缀）。该文件必须放置在网站的 `/.well-known/` 目录下或根目录中，且必须通过 HTTPS 安全协议访问。文件的核心结构包含三个部分：

- **applinks**：用于声明通用链接的关联规则。
- **webcredentials**：用于共享登录凭据，实现跨应用密码自动填充。
- **activitycontinuation**：用于 Handoff 功能，在设备间延续用户活动。

在通用链接场景中，`applinks` 是核心配置节点，它包含 `apps` 和 `details` 两个子属性。

### 2.2 核心配置深度解析

以一个典型的通用链接配置清单为例：

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appIDs": ["TEAMID.com.example.app1", "TEAMID.com.example.app2"],
        "paths": ["*/page-123*", "*/*.example"]
      }
    ]
  }
}
```

- **appIDs**：数组类型，包含一个或多个应用的完整标识符，格式为 `团队ID.BundleID`。团队 ID 是 Apple 开发者账号中的 10 位字母数字组合，可通过 Apple Developer Center 获取。每个应用有且只有一个唯一的 Bundle ID。

- **paths**：数组类型，定义了需要由应用处理的 URL 路径模式。支持通配符：
  - `*` 匹配任意字符序列
  - `?` 匹配单个字符
  - 路径模式可以包含通配符前缀和后缀

### 2.3 路径匹配规则

路径匹配是通用链接配置中最容易出错的环节。系统采用最长匹配原则，即当 URL 满足多个路径规则时，选择最具体的那一条。例如：

- `*/documents*` 会匹配 `/documents/abc`、`/shared/documents`
- `*/w-123*` 会匹配 `/folder/w-12345`、`/file/w-123abc`
- `*/*.pdf` 会匹配任何以 `.pdf` 结尾的路径

需要注意的是，路径匹配区分大小写，并且支持子路径匹配。推荐使用具体的路径前缀来缩小匹配范围，避免误匹配导致的应用跳转冲突。

## 三、Microsoft 365 应用通用链接配置实例详解

### 3.1 配置背景与目标

以 Microsoft 365 系列应用为例，其通用链接配置需要支持多个 Office 组件在 iOS 设备上的无缝跳转。配置清单中包含了 Loop、Word、Excel、PowerPoint、OneDrive 等多个应用的关联声明，每个应用都有包含团队 ID 和 Bundle ID 的精确标识符组合。这种多应用配置的核心目标是：确保当用户在任何场景下点击 Office 文档链接时，系统能够准确判断应该启动哪个应用来处理该链接。

### 3.2 路径模式设计与文档类型支持

配置清单中的路径模式设计体现了对多种文档格式的全面支持。通过定义详细的文件扩展名规则，Microsoft 365 应用能够自动识别并处理常见的办公文档格式。例如：

- **Word 文档类型**：`.docx`、`.doc`、`.docm`、`.dotx`、`.odt`——这些是 Microsoft Word 原生支持的格式，路径模式 `*/*.docx` 可以捕获任何以 .docx 结尾的链接。
- **Excel 文档类型**：`.xlsx`、`.xls`、`.csv`、`.ods`、`.xlsb`、`.xlsm`、`.xltx`——涵盖传统表格格式和现代开放标准格式。
- **PowerPoint 文档类型**：`.pptx`、`.ppt`、`.odp`、`.potm`、`.potx`、`.pps`、`.ppsm`、`.ppsx`、`.pptm`——包括演示文稿、模板、幻灯片放映等多种格式。
- **Loop 组件**：`.fluid` 格式是 Microsoft Loop 的专有格式，路径模式 `*/fl-59584e83*` 和 `*/*.fluid` 共同覆盖了这一新型协作内容类型。

### 3.3 应用特异性路径设计

每个应用除了使用文件扩展名匹配外，还定义了自定义的路径前缀。这些路径前缀通常包含应用的缩写标识符和特殊编码片段，以确保链接能够精准路由到正确的处理应用。例如：

- Word 应用使用了 `w-59584e83` 路径模式，这个模式可能对应 Word 文档的共享链接中的特定标识符，后缀 `59584e83` 可能是共享链接中用于识别特定文档或用户的编码。
- Excel 应用使用 `x-59584e83`，与 Word 的路径模式类似，只是前缀标志不同。
- PowerPoint 应用使用 `p-59584e83`。
- Loop 应用使用 `fl-59584e83`，其中的 `fl` 可能代表 Fluid Loop，这是 Loop 组件的标识。
- OneDrive 应用使用 `od-59584e83`、`x-59584e83`、`p-59584e83`、`b-59584e83` 等多种前缀模式，以覆盖用户在 OneDrive 中访问的不同类型的内容，其中 `b-59584e83` 可能代表备份或特定类型的文件。

### 3.4 多应用协调策略

在拥有多个相关联的应用时，配置策略的关键是避免路径冲突。Microsoft 365 应用采用以下策略实现和谐共存：

1. **层级分明**：Office Mobile 作为全能应用，覆盖了 Word、Excel、PowerPoint、OneDrive、Loop 的全部路径模式和文件类型，确保任何 Office 文档链接都能被处理。
2. **主次有序**：专题应用（如专门的 Word 应用）只处理与其专业领域密切相关的文档类型和路径模式，将其他类型的链接交由 Office Mobile 或对应专题应用处理。
3. **冗余覆盖**：Excel 和 PowerPoint 等专题应用与 Office Mobile 在路径声明上存在冗余，但这种冗余并非缺陷：当用户安装了专题应用时，系统会优先匹配专题应用处理对应文件类型；当未安装专题应用时，Office Mobile 能提供兜底服务。

## 四、通用链接的配置与调试实践

### 4.1 服务器端配置步骤

1. **创建 AASA 文件**：使用 JSON 格式编写配置内容，确保语法正确、无多余尾逗号。推荐使用 `JSONLint` 等工具进行验证。
2. **文件命名规范**：文件名必须为 `apple-app-site-association`，不包含任何文件扩展名。系统会自动查找这个精确的文件名。
3. **文件放置位置**：有两个可选位置，系统会优先检查 `/.well-known/apple-app-site-association`，然后检查 `/apple-app-site-association`。推荐使用 `.well-known` 目录，这是业界标准做法。
4. **HTTPS 访问验证**：确保可以通过 `https://你的域名/.well-known/apple-app-site-association` 访问该文件。文件不能包含任何重定向，系统只接受直接 200 响应。

### 4.2 客户端配置要点

1. **配置 Associated Domains**：在 Xcode 中为每个应用配置 Associated Domains，格式为 `applinks:你的域名`。支持多个域名，每个域名单独一行。
2. **实现应用代理方法**：在应用代理（App Delegate）中实现 `application:continueUserActivity:restorationHandler:` 方法来处理通用链接。需要从 `NSUserActivity` 对象中提取 URL，并根据 URL 路径进行导航。
3. **添加 capability**：在 Xcode 的 Signing & Capabilities 界面中开启 Associated Domains capability 并添加所有需要支持的域名。

### 4.3 测试与调试方法

1. **AASA 文件验证**：使用 Apple 提供的验证服务 `https://search.developer.apple.com/appsearch-validation-tool/`（但该工具已停用）或使用第三方工具如 Branch 的验证工具。更直接的方法是使用命令行工具 `curl -i https://你的域名/.well-known/apple-app-site-association` 查看响应状态码和内容。
2. **真机调试**：通用链接无法在模拟器中完整测试，必须在真实 iOS 设备上进行。调试时使用系统自带的 `Notes` 应用输入链接并点击，或使用 Safari 浏览器打开包含链接的页面。
3. **日志监控**：在 Xcode 中启用调试输出，查看系统是否成功加载 AASA 文件。可以在设备上安装描述文件后，通过 Console 应用查看 `swcd`（Shared Web Credentials Daemon）服务的日志输出，它会详细记录 AASA 文件的下载和处理过程。

### 4.4 常见问题与解决方案

1. **链接无法打开应用**：最常见的原因是 AASA 文件无法访问或内容格式错误。检查文件是否放置在正确的目录、是否有重定向、JSON 格式是否正确、是否启用了 HTTPS。
2. **应用跳转到错误的页面**：检查路径匹配规则是否过于宽泛。如果多条规则匹配同一个 URL，系统会选择最具体的那一条。
3. **只有部分文档类型生效**：检查 AASA 文件中的路径声明是否覆盖了所有期望的文档格式，同时确保应用端的路径处理逻辑与文件中的路径声明一致。
4. **更新后不生效**：系统会缓存 AASA 文件，iOS 上的缓存周期可能长达几天。可以在设备设置中关闭 Wi-Fi 然后再重新连接（触发网络配置更新），或在调试时临时修改路径模式并重试。

## 五、最佳实践与性能优化建议

### 5.1 维护 AASA 文件的策略

- **文件精简原则**：只声明确实需要处理的路径和文件类型，避免过度声明导致的维护成本增加。
- **版本控制**：将 AASA 文件纳入版本控制系统，记录每次变更的时间和原因，便于追踪问题。
- **监控与告警**：建立对 AASA 文件可访问性的监控机制，在文件无法访问时及时告警。
- **渐进式声明**：在添加新的路径模式时，可以先在小范围内测试，确认无误后再推广到所有配置。

### 5.2 提升用户触达效率

- **引导提示**：在 Web 页面中提供智能引导，提示用户“在应用中打开”或“继续在 App 中查看”，提升用户使用通用链接的意愿。
- **错误处理**：当应用无法处理某个链接时，提供明确的错误提示和替代方案，避免用户困惑。
- **性能优化**：缩短应用启动时间，实现预加载和初始化，确保从打开应用到展示内容的过程流畅无中断。

### 5.3 安全注意事项

- **防止劫持**：确保只有受信任的团队和服务器才能修改 AASA 文件，使用安全的部署流程。
- **证书管理**：HTTPS 证书必须有效且在有效期内，任何证书问题都会导致通用链接失效。
- **路径验证**：在处理用户通过通用链接传递的路径参数时，必须进行严格的输入验证和清理，防止路径遍历攻击。

## 结语

通用链接技术为 iOS 应用提供了优雅的 Web 到原生应用的桥梁，而 Apple App Site Association 文件则是这座桥梁的基石。通过深入理解 AASA 文件的配置原理、路径匹配规则以及多应用协调策略，开发者可以构建出既高效又稳定的链接跳转系统。从 Microsoft 365 系列应用的配置实例中可以看到，精心设计的路径模式和全面的文件类型支持是实现无缝用户体验的关键。在配置过程中，保持对细节的关注、严格的测试验证以及持续的维护优化，是确保通用链接长期稳定运行的根本保障。随着移动生态系统的不断演进，掌握通用链接的核心技术将为用户带来更加流畅、智能的应用体验。