跳转到内容
Tauri

深层链接

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

支持的平台

此插件需要至少 1.77.2 版本的 Rust

平台 级别 备注
Windows
Linux
Macos

运行时深层链接注册不受支持

Android

运行时深层链接注册不受支持

iOS

运行时深层链接注册不受支持

设置

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

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

npm run tauri add deep-link

设置

Android

对于 应用链接,您需要一个带有 .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

iOS

对于 通用链接,您需要一个带有 .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/"
}
]
}
]
}
}

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

为了验证您的域名是否已正确配置以公开应用关联,您可以运行以下命令,用您的实际主机名替换 <host>

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

有关更多信息,请参阅 applinks.details

桌面环境

在 Linux 和 Windows 上,深链接作为命令行参数传递给新的应用进程。如果您希望有独立的实例接收事件,深链接插件已与 单实例 插件集成。

  • 首先必须将 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());
}

用户可以通过将 URL 以参数形式包括在内来手动触发一个模拟的深链接。Tauri 会将命令行参数与配置的方案进行匹配以缓解这种情况,但您仍然应该检查 URL 是否与您预期的格式相匹配。

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

配置

tauri.conf.json > plugins > deep-link 下配置您想与应用程序关联的域名(移动端)和方案(桌面端)

tauri.conf.json
{
"plugins": {
"deep-link": {
"mobile": [
{ "host": "your.website.com", "pathPrefix": ["/open"] },
{ "host": "another.site.br" }
],
"desktop": {
"schemes": ["something", "my-tauri-app"]
}
}
}
}

按照上述配置,something://*my-tauri-app://* URL 与您的桌面应用程序相关联,在移动端,https://another.site.br/*https://your.website.com/open/* URL 将打开您的移动应用程序。

使用方法

深链接插件既可用作 JavaScript 也可用于 Rust。

当深链接触发您的应用程序打开时,将执行 onOpenUrl 回调

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

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

在 Linux 和 Windows 上,您还可以通过 register Rust 函数在运行时将方案与应用程序关联。

在以下片段中,我们将运行时注册 my-app 方案。启动应用程序后,操作系统将使用应用程序打开 my-app://* URL。

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");
}

测试

测试您的应用程序的深链有一些注意事项。

桌面环境

深链仅在桌面已安装的应用程序中触发。在 Linux 和 Windows 上,您可以使用 register_all Rust 函数来绕过此限制,该函数将所有配置的协议注册为触发当前可执行文件

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");
}

Windows

要触发 Windows 上的深链,您可以在浏览器中打开 <scheme>://url 或在终端中运行以下命令

终端窗口
start <scheme>://url

Linux

要触发 Linux 上的深链,您可以在浏览器中打开 <scheme>://url 或在终端中运行 xdg-open

终端窗口
xdg-open <scheme>://url

iOS

要触发 iOS 上的应用链接,您可以在浏览器中打开 https://<host>/path URL。对于模拟器,您可以使用 simctl CLI 从终端直接打开链接

终端窗口
xcrun simctl openurl booted https://<host>/path

Android

要触发 Android 上的应用链接,您可以在浏览器中打开 https://<host>/path URL。对于仿真器,您可以使用 adb CLI 从终端直接打开链接

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

权限

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

有关更多信息,请参阅能力概述和如何使用插件权限的分步指南

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"
]
}

默认权限

允许通过 get_current 命令读取打开的深链

  • allow-get-current

权限表

标识符 描述

deep-link:allow-get-current

启用 get_current 命令,不需要任何预配置的作用域。

deep-link:deny-get-current

拒绝 get_current 命令,不需要任何预配置的作用域。

deep-link:allow-is-registered

启用 is_registered 命令,不需要任何预配置的作用域。

deep-link:deny-is-registered

拒绝 is_registered 命令,不需要任何预配置的作用域。

deep-link:allow-register

启用 register 命令,不需要任何预配置的作用域。

deep-link:deny-register

拒绝 register 命令,不需要任何预配置的作用域。

deep-link:allow-unregister

启用 unregister 命令,不需要任何预配置的作用域。

deep-link:deny-unregister

拒绝 unregister 命令,不需要任何预配置的作用域。


© 2025 Tauri 贡献者. CC-BY / MIT