深度链接

GitHub npm crates.io

API Reference

将你的 Tauri 应用设置为 URL 的默认处理程序。

🌐 Set your Tauri application as the default handler for an URL.

支持的平台

🌐 Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos		Deep links must be registered in config. Dynamic registration at runtime is not supported.
android		Deep links must be registered in config. Dynamic registration at runtime is not supported.
ios		Deep links must be registered in config. Dynamic registration at runtime is not supported.

设置

🌐 Setup

安装深层链接插件即可开始使用。

🌐 Install the deep-link plugin to get started.

Automatic

使用项目的包管理器添加依赖：

npm

npm run tauri add deep-link

yarn

yarn run tauri add deep-link

pnpm

pnpm tauri add deep-link

deno

deno task tauri add deep-link

bun

bun tauri add deep-link

cargo

cargo tauri add deep-link

Manual

1. 在 src-tauri 文件夹中运行以下命令，将插件添加到 Cargo.toml 中的项目依赖：

   cargo add tauri-plugin-deep-link@2.0.0

2. 修改 lib.rs 以初始化插件：

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_deep_link::init())
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. 使用你偏好的 JavaScript 包管理器安装 JavaScript Guest 绑定：

   npm

   npm install @tauri-apps/plugin-deep-link

   yarn

   yarn add @tauri-apps/plugin-deep-link

   pnpm

   pnpm add @tauri-apps/plugin-deep-link

   deno

   deno add npm:@tauri-apps/plugin-deep-link

   bun

   bun add @tauri-apps/plugin-deep-link

设置

🌐 Setting up

Android

有两种方法可以通过 Android 上的链接打开你的应用：

🌐 There are two ways to open your app from links on Android:

1. 应用链接（http/https + 主机，已验证） 对于应用链接，你需要一个具有 .well-known/assetlinks.json 端点的服务器，该端点必须以给定格式返回文本响应：

.well-known/assetlinks.json

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "$APP_BUNDLE_ID",
      "sha256_cert_fingerprints": [
        $CERT_FINGERPRINT
      ]
    }
  }
]

其中 $APP_BUNDLE_ID 是在 tauri.conf.json > identifier 上定义的值，- 被替换为 _，并且 $CERT_FINGERPRINT 是你的应用签名证书的 SHA256 指纹列表，更多信息请参见 [验证 Android applinks]。

🌐 Where $APP_BUNDLE_ID is the value defined on tauri.conf.json > identifier with - replaced with _ and $CERT_FINGERPRINT is a list of SHA256 fingerprints of your app’s signing certificates, see verify Android applinks for more information.

2. 自定义 URI 方案（无需主机，无需验证） 对于像 myapp://... 这样的 URI，你可以声明一个自定义方案而无需托管任何文件。在移动配置中使用 scheme 字段，并省略 host。

iOS

有两种方法可以通过 iOS 上的链接打开你的应用：

🌐 There are two ways to open your app from links on iOS:

1. 通用链接（https + 主机，已验证） 对于[通用链接]，你需要一个带有 .well-known/apple-app-site-association 端点的服务器，该端点必须以给定格式返回 JSON 响应：

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

{
  "applinks": {
    "details": [
      {
        "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"],
        "components": [
          {
            "/": "/open/*",
            "comment": "Matches any URL whose path starts with /open/"
          }
        ]
      }
    ]
  }
}

Note

响应 Content-Type 头必须是 application/json。

.well-known/apple-app-site-association 端点必须通过 HTTPS 提供服务。 要测试本地主机，你可以使用自签名的 TLS 证书并将其安装在 iOS 模拟器上，或使用像 ngrok 这样的服务。

🌐 The .well-known/apple-app-site-association endpoint must be served over HTTPS. To test localhost you can either use a self-signed TLS certificate and install it on the iOS simulator or use services like ngrok. :::

其中 $DEVELOPMENT_TEAM_ID 是在 tauri.conf.json > tauri > bundle > iOS > developmentTeam 上定义的值或 TAURI_APPLE_DEVELOPMENT_TEAM 环境变量的值，$APP_BUNDLE_ID 是在 tauri.conf.json > identifier 上定义的值。

🌐 Where $DEVELOPMENT_TEAM_ID is the value defined on tauri.conf.json > tauri > bundle > iOS > developmentTeam or the TAURI_APPLE_DEVELOPMENT_TEAM environment variable and $APP_BUNDLE_ID is the value defined on tauri.conf.json > identifier.

要验证你的域是否已正确配置以公开应用关联，你可以运行以下命令，将 <host> 替换为你的实际主机：

🌐 To verify if your domain has been properly configured to expose the app associations, you can run the following command, replacing <host> with your actual host:

curl -v https://app-site-association.cdn-apple.com/a/v1/<host>

有关更多信息，请参见 applinks.details。

🌐 See applinks.details for more information.

2. 自定义 URI 方案（无主机，无验证） 对于像 myapp://... 这样的 URI，你可以在移动配置中使用 "appLink": false 声明自定义方案（也可以省略）。该插件会在你的应用的 Info.plist 中生成相应的 CFBundleURLTypes 条目。无需 .well-known 文件或 HTTPS 主机。

桌面

🌐 Desktop

在 Linux 和 Windows 上，深度链接作为命令行参数传递给新的应用进程。 如果你希望让唯一的应用实例接收事件，深度链接插件可以与 single instance 插件集成。

🌐 On Linux and Windows deep links are delivered as a command line argument to a new app process. The deep link plugin has integration with the single instance plugin if you prefer having a unique app instance receiving the events.

• 首先，你必须将 deep-link 功能添加到单实例插件中：

src-tauri/Cargo.toml

[target."cfg(any(target_os = \"macos\", windows, target_os = \"linux\"))".dependencies]
tauri-plugin-single-instance = { version = "2.0.0", features = ["deep-link"] }

• 然后配置单实例插件，该插件应始终是你注册的第一个插件：

src-tauri/lib.rs

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let mut builder = tauri::Builder::default();

    #[cfg(desktop)]
    {
        builder = builder.plugin(tauri_plugin_single_instance::init(|_app, argv, _cwd| {
          println!("a new app instance was opened with {argv:?} and the deep link event was already triggered");
          // when defining deep link schemes at runtime, you must also check `argv` here
        }));
    }

    builder = builder.plugin(tauri_plugin_deep_link::init());
}

Caution

用户可以通过将 URL 作为参数包含来手动触发假深层链接。Tauri 会将命令行参数与配置的方案进行匹配以减轻这种情况，但你仍然应该检查 URL 是否符合你期望的格式。

这意味着 Tauri 只处理为静态配置的方案的深层链接，而在运行时注册的方案必须使用 Env::args_os 手动检查。

🌐 This means Tauri only handles deep links for schemes that were statically configured, and schemes registered at runtime must be manually checked using Env::args_os. :::

配置

🌐 Configuration

在 tauri.conf.json > plugins > deep-link 下，配置你希望与应用关联的移动域/方案和桌面方案。

🌐 Under tauri.conf.json > plugins > deep-link, configure mobile domains/schemes and desktop schemes you want to associate with your application.

示例

🌐 Examples

移动端自定义方案（无需服务器）：

tauri.conf.json

{
  "plugins": {
    "deep-link": {
      "mobile": [
        {
          "scheme": ["ovi"],
          "appLink": false
        }
      ]
    }
  }
}

这会在 Android 和 iOS 上注册 ovi://* 方案。

🌐 This registers the ovi://* scheme on Android and iOS.

应用链接 / 通用链接（已验证 https + 主机）：

{
  "plugins": {
    "deep-link": {
      "mobile": [
        {
          "scheme": ["https"],
          "host": "your.website.com",
          "pathPrefix": ["/open"],
          "appLink": true
        }
      ]
    }
  }
}

这将 https://your.website.com/open/* 注册为应用/通用链接。

🌐 This registers https://your.website.com/open/* as an app/universal link.

桌面自定义方案：

{
  "plugins": {
    "deep-link": {
      "desktop": {
        "schemes": ["something", "my-tauri-app"]
      }
    }
  }
}

使用

🌐 Usage

深层链接插件在 JavaScript 和 Rust 中都可用。

🌐 The deep-link plugin is available in both JavaScript and Rust.

监听深层链接

🌐 Listening to Deep Links

JavaScript

当深度链接在应用运行时触发你的应用时，会调用 onOpenUrl 回调。要检测你的应用是否通过深度链接打开，请在应用启动时使用 getCurrent。

🌐 When a deep link triggers your app while it’s running, the onOpenUrl callback is called. To detect whether your app was opened via a deep link, use getCurrent on app start.

import { getCurrent, onOpenUrl } from '@tauri-apps/plugin-deep-link';
// when using `"withGlobalTauri": true`, you may use
// const { getCurrent, onOpenUrl } = window.__TAURI__.deepLink;

const startUrls = await getCurrent();
if (startUrls) {
  // App was likely started via a deep link
  // Note that getCurrent's return value will also get updated every time onOpenUrl gets triggered.
}

await onOpenUrl((urls) => {
  console.log('deep link:', urls);
});

Rust

当深层链接在应用运行时触发你的应用时，插件的 on_open_url 闭包会被调用。要检测你的应用是否通过深层链接打开，请在应用启动时使用 get_current。

🌐 When a deep link triggers your app while it’s running, the plugin’s on_open_url closure is called. To detect whether your app was opened via a deep link, use get_current on app start.

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            // Note that get_current's return value will also get updated every time on_open_url gets triggered.
            let start_urls = app.deep_link().get_current()?;
            if let Some(urls) = start_urls {
                // app was likely started by a deep link
                println!("deep link URLs: {:?}", urls);
            }

            app.deep_link().on_open_url(|event| {
                println!("deep link URLs: {:?}", event.urls());
            });
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Note

打开 URL 事件会触发一个包含请求与 macOS 深度链接 API 兼容的 URL 列表的事件，但在大多数情况下，你的应用只会接收到单个 URL。

在运行时注册桌面深层链接

🌐 Registering Desktop Deep Links at Runtime

配置部分描述了如何为你的应用定义静态深度链接方案。

🌐 The configuration section describes how to define static deep link schemes for your application.

在 Linux 和 Windows 上，也可以通过 register Rust 函数在运行时将方案与你的应用关联。

🌐 On Linux and Windows it is possible to also associate schemes with your application at runtime via the register Rust function.

在以下片段中，我们将在运行时注册 my-app 方案。第一次执行应用后，操作系统将使用我们的应用打开 my-app://* URL：

🌐 In the following snippet, we will register the my-app scheme at runtime. After executing the app for the first time, the operating system will open my-app://* URLs with our application:

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(desktop)]
            app.deep_link().register("my-app")?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Note

在运行时注册深度链接对于在 Linux 和 Windows 上开发非常有用，因为默认情况下，深度链接仅在你的应用安装时注册。

安装 AppImage 可能很复杂，因为它需要 AppImage 启动器。

🌐 Installing an AppImage can be complicated as it requires an AppImage launcher.

在运行时注册深度链接可能更可取，因此 Tauri 还包含一个辅助函数来在运行时强制注册所有静态配置的深度链接。调用此函数还可确保在开发模式下注册深度链接：

🌐 Registering the deep links at runtime might be preferred, so Tauri also includes a helper function to force register all statically configured deep links at runtime. Calling this function also ensures the deep links is registered for development mode:

#[cfg(any(target_os = "linux", all(debug_assertions, windows)))]
{
  use tauri_plugin_deep_link::DeepLinkExt;
  app.deep_link().register_all()?;
}

测试

🌐 Testing

测试应用的深层链接时有一些注意事项。

🌐 There are some caveats to test deep links for your application.

桌面

🌐 Desktop

深层链接仅会对桌面上已安装的应用触发。在 Linux 和 Windows 上，你可以使用 register_all Rust 函数绕过这一限制，该函数会注册所有已配置的方案以触发当前的可执行文件：

🌐 Deep links are only triggered for installed applications on desktop. On Linux and Windows you can circumvent this using the register_all Rust function, which registers all configured schemes to trigger the current executable:

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(any(windows, target_os = "linux"))]
            {
                use tauri_plugin_deep_link::DeepLinkExt;
                app.deep_link().register_all()?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Note

在 Linux 上安装支持深度链接的 AppImage 需要一个 AppImage 启动器，将 AppImage 与操作系统集成。 使用 register_all 功能，你可以开箱即用地支持深度链接，而无需用户使用外部工具。

当 AppImage 被移动到文件系统中的不同位置时，深度链接会失效，因为它依赖于可执行文件的绝对路径，这也使得在运行时注册方案更加重要。

🌐 When the AppImage is moved to a different location in the file system, the deep link is invalidated since it leverages an absolute path to the executable, which makes registering the schemes at runtime even more important.

请参阅 运行时注册桌面深度链接 部分以获取更多信息。

🌐 See the Registering Desktop Deep Links at Runtime section for more information. :::

Caution

在 macOS 上无法在运行时注册深度链接，因此深度链接只能在打包的应用上进行测试，该应用必须安装在 /Applications 目录中。

Windows

要在 Windows 上触发深度链接，你可以在浏览器中打开 <scheme>://url 或在终端中运行以下命令：

🌐 To trigger a deep link on Windows you can either open <scheme>://url in the browser or run the following command in the terminal:

start <scheme>://url

Linux

要在 Linux 上触发深度链接，你可以在浏览器中打开 <scheme>://url 或在终端中运行 xdg-open：

🌐 To trigger a deep link on Linux you can either open <scheme>://url in the browser or run xdg-open in the terminal:

xdg-open <scheme>://url

iOS

要在 iOS 上触发应用链接，你可以在浏览器中打开 https://<host>/path URL。对于模拟器，你可以利用 simctl 命令行工具直接从终端打开链接：

xcrun simctl openurl booted https://<host>/path

Android

要在 Android 上触发应用链接，你可以在浏览器中打开 https://<host>/path URL。对于模拟器，你可以利用 adb 命令行工具直接从终端打开链接：

adb shell am start -a android.intent.action.VIEW -d https://<host>/path <bundle-identifier>

权限

🌐 Permissions

默认情况下，所有潜在危险的插件命令和作用域都会被阻止，无法访问。你必须在 capabilities 配置中修改权限以启用这些功能。

🌐 By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

有关更多信息，请参见功能概览，有关使用插件权限的分步指南，请参见分步指南。

🌐 See the Capabilities Overview for more information and the step by step guide to use plugin permissions.

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    // Usually you will need core:event:default to listen to the deep-link event
    "core:event:default",
    "deep-link:default"
  ]
}

Default Permission

Allows reading the opened deep link via the get_current command

This default permission set includes the following:

• allow-get-current

Permission Table

Identifier	Description
deep-link:allow-get-current	Enables the get_current command without any pre-configured scope.
deep-link:deny-get-current	Denies the get_current command without any pre-configured scope.
deep-link:allow-is-registered	Enables the is_registered command without any pre-configured scope.
deep-link:deny-is-registered	Denies the is_registered command without any pre-configured scope.
deep-link:allow-register	Enables the register command without any pre-configured scope.
deep-link:deny-register	Denies the register command without any pre-configured scope.
deep-link:allow-unregister	Enables the unregister command without any pre-configured scope.
deep-link:deny-unregister	Denies the unregister command without any pre-configured scope.