博客更新日志 GitHub 简中文档

首页指南 EAS 参考学习

存档 Expo Snack Discord 和论坛新闻邮件

iOS 通用链接

编辑页面

了解如何配置 iOS 通用链接，以便从标准网页 URL 打开你的 Expo 应用。

要为你的应用配置 iOS Universal Links，你需要设置双向关联来验证你的网站和原生应用。

观看：使用 Expo Router 设置 iOS Universal Links

观看：使用 Expo Router 设置 iOS Universal Links

了解如何配置 iOS Universal Links，以便你的 Expo 应用能够从标准网页 URL 打开。

设置双向关联

要在 iOS 上在网站和应用之间建立双向关联，你需要执行以下步骤：

网站验证：这需要在 /.well-known 目录中创建一个 apple-app-site-association (AASA) 文件，并将其托管在目标网站上。此文件用于验证从给定链接打开的应用是否为正确的应用。
原生应用验证：这需要某种形式的代码签名，并引用目标网站域名（URL）。

创建 AASA 文件

在 /.well-known 目录中创建一个用于网站验证的 apple-app-site-association 文件。该文件指定你的 Apple Developer Team ID、bundle identifier，以及一组支持的路径，用于重定向到原生应用。

你可以在项目中运行 experimental CLI 命令 npx setup-safari，自动向你的 Apple 账户注册一个 bundle identifier，为该 ID 分配权限，并在商店中创建一个 iTunes 应用条目。系统会打印本地设置，你可以跳过下面的大部分步骤。这是在 iOS 上开始使用 universal links 最简单的方式。

如果你使用 Expo Router 构建网站（或任何其他现代 React 框架，例如 Remix、Next.js 等），请在 public/.well-known/apple-app-site-association 创建 AASA 文件。对于旧版 Expo webpack 项目，请在 web/.well-known/apple-app-site-association 创建该文件。

public/.well-known/apple-app-site-association

{
  // 此部分启用 Universal Links
  "applinks": {
    "apps": [],
    "details": [
      {
        // 语法："<APPLE_TEAM_ID>.<BUNDLE_ID>"
        "appID": "QQ57RJ5UTD.com.example.myapp",
        // 所有应该支持重定向的路径。
        "paths": ["/records/*"]
      }
    ]
  },
  // 此部分启用 Apple Handoff
  "activitycontinuation": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  },
  // 此部分启用共享网页凭据
  "webcredentials": {
    "apps": ["<APPLE_TEAM_ID>.<BUNDLE_ID>"]
  }
}

在上面的示例中：

指向 https://www.myapp.io/records/* 的任何链接（对记录 ID 使用通配符匹配）都应在 iOS 设备上由匹配 bundle identifier 的应用直接打开。它由 Apple Team ID 和 bundle identifier 组成。
* 通配符不会匹配域名或路径分隔符（句点和斜杠）。
activitycontinuation 和 webcredentials 对象是可选的，但建议保留。

参见 Apple 的文档以了解 AASA 格式的更多细节。Branch 提供了一个 AASA 验证器，可以帮助你确认 AASA 是否已正确部署并且格式有效。

支持 `details` 格式

details 格式已被支持自 iOS 13 起。它允许你指定：

使用 appIDs 代替 appID：更容易将多个应用与相同配置关联起来
一个 components 数组：允许你指定 fragment、排除特定路径，并添加注释

Apple 文档中的一个 AASA JSON 示例

public/.well-known/apple-app-site-association

{
  "applinks": {
    "details": [
      {
        "appIDs": ["ABCDE12345.com.example.app", "ABCDE12345.com.example.app2"],
        "components": [
          {
            "#": "no_universal_links",
            "exclude": true,
            "comment": "匹配任何 fragment 等于 no_universal_links 的 URL，并指示系统不要将其作为 universal link 打开"
          },
          {
            "/": "/buy/*",
            "comment": "匹配任何路径以 /buy/ 开头的 URL"
          },
          {
            "/": "/help/website/*",
            "exclude": true,
            "comment": "匹配任何路径以 /help/website/ 开头的 URL，并指示系统不要将其作为 universal link 打开"
          },
          {
            "/": "/help/*",
            "?": {
              "articleNumber": "????"
            },
            "comment": "匹配任何路径以 /help/ 开头、且包含一个名为 'articleNumber' 的查询项并且其值恰好为 4 个字符的 URL"
          }
        ]
      }
    ]
  }
}

为了支持所有 iOS 版本，你可以在 details 键中同时提供上述两种格式，但我们建议将较新的 iOS 版本配置放在前面。

托管 AASA 文件

使用你的域名和 Web 服务器托管 apple-app-site-association 文件。该文件必须通过 HTTPS 连接提供。请确认你的浏览器可以访问该文件。

在设置好 AASA 文件后，将你的网站部署到支持 HTTPS 的服务器上（大多数现代 Web 托管服务都支持）。

原生应用配置

在部署你的 apple-app-site-association（AASA）文件后，通过在你的 app 配置中添加 ios.associatedDomains 来将应用配置为使用关联域。请务必遵循 Apple 指定的格式，并且不要在 URL 中包含协议（https）。这是一个常见错误，会导致 universal links 无法工作。

例如，如果关联的网站是 https://expo.dev/，则 applinks 为：

app.json

{
  "expo": {
    "ios": {
      "associatedDomains": ["applinks:expo.dev"]
    }
  }
}

使用 EAS Build 构建你的 iOS 应用，它会确保该 entitlement 自动向 Apple 注册。

手动原生配置

如果你没有使用 EAS 或 Continuous Native Generation（npx expo prebuild），你必须为你的 bundle identifier 手动配置 Associated Domains 功能。

如果你通过 Apple Developer Console 启用，那么请确保在你的 ios/[app]/[app].entitlements 文件中添加以下 entitlements：

<key>com.apple.developer.associated-domains</key>
<array>
  <string>applinks:expo.dev</string>
</array>

原生应用验证

在你的 iOS 设备上安装该应用以触发验证过程。你移动设备上指向网站的链接应该会打开你的应用。如果没有，请重新检查前面的步骤，确保你的 AASA 有效、AASA 中指定的路径正确，并且你已在 Apple Developer Console 中正确配置了你的 App ID。

当你的应用打开后，请参阅处理进入你应用的链接以了解更多关于如何处理传入链接并向用户显示其请求内容的信息。

iOS 会在你的应用首次安装时或从 App Store 安装更新时下载你的 AASA。之后操作系统不会频繁刷新。如果你想为生产应用更改 AASA 中的路径，则需要通过 App Store 发布一次完整更新，以便所有用户的应用重新获取你的 AASA 并识别新的路径。

Apple Smart Banner

如果用户没有安装你的应用，他们将被引导到网站。你可以使用 Apple Smart Banner 在页面顶部显示一个横幅，提示用户安装应用。该横幅仅在用户使用移动设备且未安装应用时显示。

要启用横幅，请在网站的 <head> 中添加以下 meta 标签，并将 <ITUNES_ID> 替换为你应用的 iTunes ID：

<meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />

如果你在设置横幅时遇到问题，请运行以下命令以自动为你的项目生成 meta 标签：

Terminal

- npx setup-safari

将 meta 标签添加到静态渲染的网站

如果你正在构建一个使用 Expo Router 的静态渲染网站，那么请将 HTML 标签添加到 src/app/+html.js 文件的 <head> 组件中。

src/app/+html.tsx

import { type PropsWithChildren } from 'react';

export default function Root({ children }: PropsWithChildren) {
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta httpEquiv="X-UA-Compatible" content="IE=edge" />
        <meta name="apple-itunes-app" content="app-id=<ITUNES_ID>" />
        {/* 其他 head 元素... */}
      </head>
      <body>{children}</body>
    </html>
  );
}

调试

Expo CLI 允许你在不部署网站的情况下测试 iOS Universal Links。利用 --tunnel 功能，你可以将开发服务器转发到一个公开可访问的 HTTPS URL。

1

将环境变量 EXPO_TUNNEL_SUBDOMAIN=my-custom-domain 设置为其中 my-custom-domain 是你在开发期间使用的唯一字符串。这样可以确保你的 tunnel URL 在开发服务器重启之间保持一致。

2

按照上文所述，在你的 app 配置中添加 associatedDomains。将域名值替换为一个 Ngrok URL：my-custom-domain.ngrok.io。

3

使用 --tunnel 标志启动你的开发服务器：

Terminal

- npx expo start --tunnel

4

在你的设备上编译开发构建：

Terminal

- npx expo run:ios

现在你可以在设备的网页浏览器中输入你的自定义域名链接来打开你的应用。

故障排查

以下是一些常见提示，可帮助你在实现 iOS Universal Links 时进行故障排查：

阅读 Apple 关于调试 universal links 的官方文档
使用验证工具确保你的 apple app site association 文件有效。
未压缩的 apple-app-site-association 文件不能大于 128kb。
确保你的网站通过 HTTPS 提供服务。
如果你更新了网页文件，请重新构建原生应用，以触发供应商端（Apple）的服务器更新。