Capacitor深度链接实现指南：自定义URL方案、通用链接与应用链接配置

capacitor-deep-linking by cap-go/capgo-skills

144 周安装量

24 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/cap-go/capgo-skills --skill capacitor-deep-linking

iOS 移动应用 JavaScript 框架

🇨🇳中文介绍

Capacitor 中的深度链接

在 Capacitor 应用中实现深度链接、通用链接和应用链接。

何时使用此技能

用户想要深度链接
用户需要通用链接
用户询问 URL 方案
用户希望通过链接打开应用
用户需要分享链接

深度链接类型

类型	平台	格式	需要服务器
自定义 URL 方案	两者皆可	`myapp://path`	否
通用链接	iOS	`https://myapp.com/path`	是
应用链接	Android	`https://myapp.com/path`

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

Node.js后端模式指南：构建可扩展REST API、微服务与实时应用

19,300 周安装

Next.js 16+ 缓存组件指南：实现部分预渲染（PPR）与混合内容缓存

16,500 周安装

Vue 3 调试指南：解决响应式、计算属性与监听器常见错误

11,900 周安装

Genkit JS 开发指南：AI 应用构建、错误排查与最佳实践

7,000 周安装

import { App } from '@capacitor/app';

// 监听深度链接打开事件
App.addListener('appUrlOpen', (event) => {
  console.log('应用通过 URL 打开：', event.url);

  // 解析并导航
  const url = new URL(event.url);
  handleDeepLink(url);
});

function handleDeepLink(url: URL) {
  // 自定义方案：myapp://product/123
  // 通用链接：https://myapp.com/product/123

  const path = url.pathname || url.host + url.pathname;

  // 根据路径路由
  if (path.startsWith('/product/')) {
    const productId = path.split('/')[2];
    navigateTo(`/product/${productId}`);
  } else if (path.startsWith('/user/')) {
    const userId = path.split('/')[2];
    navigateTo(`/profile/${userId}`);
  } else if (path === '/login') {
    navigateTo('/login');
  } else {
    navigateTo('/');
  }
}

<!-- android/app/src/main/AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <!-- 深度链接意图过滤器 -->
    <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="myapp" />
    </intent-filter>
</activity>

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourcompany.yourapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

<!-- android/app/src/main/AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <!-- 应用链接意图过滤器 -->
    <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="https" />
        <data android:host="myapp.com" />
        <data android:pathPrefix="/product" />
        <data android:pathPrefix="/user" />
        <data android:pathPrefix="/invite" />
    </intent-filter>
</activity>

import { App } from '@capacitor/app';
import { useHistory } from 'react-router-dom';
import { useEffect } from 'react';

function DeepLinkHandler() {
  const history = useHistory();

  useEffect(() => {
    App.addListener('appUrlOpen', (event) => {
      const url = new URL(event.url);
      const path = getPathFromUrl(url);

      // 使用 React Router 导航
      history.push(path);
    });

    // 检查应用是否通过 URL 打开
    App.getLaunchUrl().then((result) => {
      if (result?.url) {
        const url = new URL(result.url);
        const path = getPathFromUrl(url);
        history.push(path);
      }
    });
  }, []);

  return null;
}

function getPathFromUrl(url: URL): string {
  // 处理自定义方案和 https
  if (url.protocol === 'myapp:') {
    return '/' + url.host + url.pathname;
  }
  return url.pathname + url.search;
}

import { App } from '@capacitor/app';
import { useRouter } from 'vue-router';
import { onMounted } from 'vue';

export function useDeepLinks() {
  const router = useRouter();

  onMounted(async () => {
    App.addListener('appUrlOpen', (event) => {
      const path = parseDeepLink(event.url);
      router.push(path);
    });

    const launchUrl = await App.getLaunchUrl();
    if (launchUrl?.url) {
      const path = parseDeepLink(launchUrl.url);
      router.push(path);
    }
  });
}

import { App } from '@capacitor/app';
import { Preferences } from '@capacitor/preferences';

// 在首次启动时，检查延迟链接
async function checkDeferredDeepLink() {
  const { value: isFirstLaunch } = await Preferences.get({ key: 'firstLaunch' });

  if (isFirstLaunch !== 'false') {
    await Preferences.set({ key: 'firstLaunch', value: 'false' });

    // 通过你的归因服务检查
    const deferredLink = await fetchDeferredLink();
    if (deferredLink) {
      handleDeepLink(new URL(deferredLink));
    }
  }
}

App.addListener('appUrlOpen', (event) => {
  const url = new URL(event.url);

  // 获取查询参数
  const source = url.searchParams.get('source');
  const campaign = url.searchParams.get('campaign');
  const referrer = url.searchParams.get('ref');

  // 跟踪归因
  analytics.logEvent('deep_link_open', {
    path: url.pathname,
    source,
    campaign,
    referrer,
  });

  // 携带状态导航
  navigateTo(url.pathname, {
    state: { source, campaign, referrer },
  });
});

// 处理 OAuth 重定向
App.addListener('appUrlOpen', async (event) => {
  const url = new URL(event.url);

  if (url.pathname === '/oauth/callback') {
    const code = url.searchParams.get('code');
    const state = url.searchParams.get('state');
    const error = url.searchParams.get('error');

    if (error) {
      handleOAuthError(error);
      return;
    }

    if (code && validateState(state)) {
      await exchangeCodeForToken(code);
      navigateTo('/home');
    }
  }
});

场景	命令
自定义方案	`myapp://path`
通用链接冷启动	应用关闭时点击链接
通用链接热启动	应用在后台时点击链接
Safari 中的通用链接	在 Safari 中输入 URL
应用链接冷启动	应用关闭时点击链接
Chrome 中的应用链接	在 Chrome 中点击链接

问题	解决方案
通用链接不工作	检查 AASA 文件、SSL、权限
应用链接未验证	检查 assetlinks.json 文件、指纹
链接在浏览器中打开	检查 intent-filter、autoVerify
冷启动未处理	使用 `App.getLaunchUrl()`
模拟器问题	重置模拟器，重新构建应用

🇺🇸English

Deep Linking in Capacitor

Implement deep links, universal links, and app links in Capacitor apps.

When to Use This Skill

User wants deep links
User needs universal links
User asks about URL schemes
User wants to open app from links
User needs share links

Types of Deep Links

Type	Platform	Format	Requires Server
Custom URL Scheme	Both	`myapp://path`	No
Universal Links	iOS	`https://myapp.com/path`	Yes
App Links	Android	`https://myapp.com/path`	Yes

Quick Start

Install Plugin

bun add @capacitor/app
bunx cap sync

Handle Deep Links

import { App } from '@capacitor/app';

// Listen for deep link opens
App.addListener('appUrlOpen', (event) => {
  console.log('App opened with URL:', event.url);

  // Parse and navigate
  const url = new URL(event.url);
  handleDeepLink(url);
});

function handleDeepLink(url: URL) {
  // Custom scheme: myapp://product/123
  // Universal link: https://myapp.com/product/123

  const path = url.pathname || url.host + url.pathname;

  // Route based on path
  if (path.startsWith('/product/')) {
    const productId = path.split('/')[2];
    navigateTo(`/product/${productId}`);
  } else if (path.startsWith('/user/')) {
    const userId = path.split('/')[2];
    navigateTo(`/profile/${userId}`);
  } else if (path === '/login') {
    navigateTo('/login');
  } else {
    navigateTo('/');
  }
}

Custom URL Scheme

iOS Configuration

<!-- ios/App/App/Info.plist -->
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.yourcompany.yourapp</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>myapp</string>
            <string>myapp-dev</string>
        </array>
    </dict>
</array>

Android Configuration

<!-- android/app/src/main/AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <!-- Deep link 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="myapp" />
    </intent-filter>
</activity>

Test Custom Scheme

# iOS Simulator
xcrun simctl openurl booted "myapp://product/123"

# Android
adb shell am start -a android.intent.action.VIEW -d "myapp://product/123"

Universal Links (iOS)

1. Enable Associated Domains

In Xcode:

Select App target
Signing & Capabilities
```
 * Capability > Associated Domains
```
Add: applinks:myapp.com

2. Create apple-app-site-association

Host at https://myapp.com/.well-known/apple-app-site-association:

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "TEAMID.com.yourcompany.yourapp",
        "paths": [
          "/product/*",
          "/user/*",
          "/invite/*",
          "NOT /api/*"
        ]
      }
    ]
  }
}

Requirements :

Served over HTTPS
Content-Type: application/json
No redirects
File at root domain

3. Info.plist

<!-- ios/App/App/Info.plist -->
<key>com.apple.developer.associated-domains</key>
<array>
    <string>applinks:myapp.com</string>
    <string>applinks:www.myapp.com</string>
</array>

Verify Universal Links

# Validate AASA file
curl -I https://myapp.com/.well-known/apple-app-site-association

# Check Apple CDN cache
curl "https://app-site-association.cdn-apple.com/a/v1/myapp.com"

App Links (Android)

1. Create assetlinks.json

Host at https://myapp.com/.well-known/assetlinks.json:

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.yourcompany.yourapp",
      "sha256_cert_fingerprints": [
        "AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99:AA:BB:CC:DD:EE:FF:00:11:22:33:44:55:66:77:88:99"
      ]
    }
  }
]

Get SHA256 Fingerprint

# Debug keystore
keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android

# Release keystore
keytool -list -v -keystore release.keystore -alias your-alias

# From APK
keytool -printcert -jarfile app-release.apk

2. AndroidManifest.xml

<!-- android/app/src/main/AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <!-- App Links 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="https" />
        <data android:host="myapp.com" />
        <data android:pathPrefix="/product" />
        <data android:pathPrefix="/user" />
        <data android:pathPrefix="/invite" />
    </intent-filter>
</activity>

Verify App Links

# Validate assetlinks.json
curl https://myapp.com/.well-known/assetlinks.json

# Use Google's validator
https://developers.google.com/digital-asset-links/tools/generator

# Check link handling on device
adb shell pm get-app-links com.yourcompany.yourapp

Advanced Routing

React Router Integration

import { App } from '@capacitor/app';
import { useHistory } from 'react-router-dom';
import { useEffect } from 'react';

function DeepLinkHandler() {
  const history = useHistory();

  useEffect(() => {
    App.addListener('appUrlOpen', (event) => {
      const url = new URL(event.url);
      const path = getPathFromUrl(url);

      // Navigate using React Router
      history.push(path);
    });

    // Check if app was opened with URL
    App.getLaunchUrl().then((result) => {
      if (result?.url) {
        const url = new URL(result.url);
        const path = getPathFromUrl(url);
        history.push(path);
      }
    });
  }, []);

  return null;
}

function getPathFromUrl(url: URL): string {
  // Handle both custom scheme and https
  if (url.protocol === 'myapp:') {
    return '/' + url.host + url.pathname;
  }
  return url.pathname + url.search;
}

Vue Router Integration

import { App } from '@capacitor/app';
import { useRouter } from 'vue-router';
import { onMounted } from 'vue';

export function useDeepLinks() {
  const router = useRouter();

  onMounted(async () => {
    App.addListener('appUrlOpen', (event) => {
      const path = parseDeepLink(event.url);
      router.push(path);
    });

    const launchUrl = await App.getLaunchUrl();
    if (launchUrl?.url) {
      const path = parseDeepLink(launchUrl.url);
      router.push(path);
    }
  });
}

Deferred Deep Links

Handle links when app wasn't installed:

import { App } from '@capacitor/app';
import { Preferences } from '@capacitor/preferences';

// On first launch, check for deferred link
async function checkDeferredDeepLink() {
  const { value: isFirstLaunch } = await Preferences.get({ key: 'firstLaunch' });

  if (isFirstLaunch !== 'false') {
    await Preferences.set({ key: 'firstLaunch', value: 'false' });

    // Check with your attribution service
    const deferredLink = await fetchDeferredLink();
    if (deferredLink) {
      handleDeepLink(new URL(deferredLink));
    }
  }
}

Query Parameters

App.addListener('appUrlOpen', (event) => {
  const url = new URL(event.url);

  // Get query parameters
  const source = url.searchParams.get('source');
  const campaign = url.searchParams.get('campaign');
  const referrer = url.searchParams.get('ref');

  // Track attribution
  analytics.logEvent('deep_link_open', {
    path: url.pathname,
    source,
    campaign,
    referrer,
  });

  // Navigate with state
  navigateTo(url.pathname, {
    state: { source, campaign, referrer },
  });
});

OAuth Callback Handling

// Handle OAuth redirect
App.addListener('appUrlOpen', async (event) => {
  const url = new URL(event.url);

  if (url.pathname === '/oauth/callback') {
    const code = url.searchParams.get('code');
    const state = url.searchParams.get('state');
    const error = url.searchParams.get('error');

    if (error) {
      handleOAuthError(error);
      return;
    }

    if (code && validateState(state)) {
      await exchangeCodeForToken(code);
      navigateTo('/home');
    }
  }
});

Testing

Test Matrix

Scenario	Command
Custom scheme	`myapp://path`
Universal link cold start	Tap link with app closed
Universal link warm start	Tap link with app in background
Universal link in Safari	Type URL in Safari
App link cold start	Tap link with app closed
App link in Chrome	Tap link in Chrome

Debug Tools

# iOS: Check associated domains entitlement
codesign -d --entitlements - App.app | grep associated-domains

# iOS: Reset Universal Links cache
xcrun simctl erase all

# Android: Check verified links
adb shell dumpsys package d | grep -A5 "Package: com.yourcompany.yourapp"

Common Issues

Issue	Solution
Universal Links not working	Check AASA file, SSL, entitlements
App Links not verified	Check assetlinks.json, fingerprint
Links open in browser	Check intent-filter, autoVerify
Cold start not handled	Use `App.getLaunchUrl()`
Simulator issues	Reset simulator, rebuild app

Resources

Capacitor App Plugin: https://capacitorjs.com/docs/apis/app
Universal Links Guide: https://developer.apple.com/documentation/xcode/supporting-universal-links-in-your-app
Android App Links: https://developer.android.com/training/app-links
Digital Asset Links Validator: https://developers.google.com/digital-asset-links/tools/generator

Weekly Installs

Repository

cap-go/capgo-skills

GitHub Stars

First Seen

Feb 6, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

gemini-cli62

opencode60

github-copilot58

codex58

amp56

kimi-cli56

Capacitor深度链接实现指南：自定义URL方案、通用链接与应用链接配置

🇨🇳中文介绍

Capacitor 中的深度链接

何时使用此技能

深度链接类型

相关 Skills

快速开始

安装插件

处理深度链接

自定义 URL 方案

iOS 配置

Android 配置

测试自定义方案

通用链接 (iOS)

1. 启用关联域名

2. 创建 apple-app-site-association 文件

3. Info.plist

验证通用链接

应用链接 (Android)

1. 创建 assetlinks.json 文件

获取 SHA256 指纹

2. AndroidManifest.xml

验证应用链接

高级路由

React Router 集成

Vue Router 集成

延迟深度链接

查询参数

OAuth 回调处理

测试

测试矩阵

调试工具

常见问题

资源

🇺🇸English

Deep Linking in Capacitor

When to Use This Skill

Types of Deep Links

Quick Start

Install Plugin

Handle Deep Links

Custom URL Scheme

iOS Configuration

Android Configuration

Test Custom Scheme

Universal Links (iOS)

1. Enable Associated Domains

2. Create apple-app-site-association

3. Info.plist

Verify Universal Links

App Links (Android)

1. Create assetlinks.json

Get SHA256 Fingerprint

2. AndroidManifest.xml

Verify App Links

Advanced Routing

React Router Integration

Vue Router Integration

Deferred Deep Links

Query Parameters

OAuth Callback Handling

Testing

Test Matrix

Debug Tools

Common Issues

Resources

最新 Skills