Flutter深度链接问题：分享URL无法唤起应用及404报错

解决方法 #

1. 配置GitHub Pages路由 fallback #

GitHub Pages为静态站点，仅存在的文件会返回内容，带userId的路径并非实际文件，需让所有路径指向index.html：

• 在项目根目录创建404.html，添加重定向逻辑保留路径参数：

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>App Redirect</title>
  <script>
    // 保留当前路径与参数，跳转到首页
    window.location.replace('/index.html' + window.location.pathname + window.location.search);
  </script>
</head>
<body>
</body>
</html>

• 若为Flutter Web项目，确保web/index.html中<base href="/">配置正确，同时Flutter路由支持处理/userId格式的路径。

2. 修正App Links路径匹配规则 #

检查apple-app-site-association和applinks.json的paths字段，确保覆盖所有带参数的子路径：

• Apple配置示例：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "你的团队ID.应用BundleID",
        "paths": ["/*"]
      }
    ]
  }
}

• Android配置同理，将paths设为["/*"]匹配所有子路径。

3. 网页端添加唤起逻辑 #

在index.html中加入JS，提取路径参数并尝试唤起App：

document.addEventListener('DOMContentLoaded', () => {
  const userId = window.location.pathname.slice(1); // 提取路径中的userId
  if (userId) {
    // 替换为你的App Scheme
    const appDeepLink = 'yourapp://open/user?userId=' + userId;
    window.location.href = appDeepLink;
    // 唤起失败时引导下载或跳转
    setTimeout(() => {
      window.location.href = '你的应用下载页面';
    }, 3000);
  }
});

替代方案 #

1. 使用Firebase Dynamic Links #

专门针对深度链接的服务，支持动态生成带参数的链接，自动处理iOS/Android的唤起逻辑，无需手动配置静态站点路由，还可统计跳转数据。

2. 短链接中转 #

将带userId的长链接生成短链接，短链接指向专门的中转页面，由中转页面处理App唤起和参数传递，避开静态站点的404限制。

内容的提问来源于stack exchange，提问作者Hyejung