解决 Tauri 中 shell.open 报错：Uncaught (in promise) shell.open not allowed URL

在基于 Tauri 开发桌面应用的过程中，相信不少开发者都遇到过权限相关的报错，其中Uncaught (in promise) shell.open not allowed URL就是高频问题之一。我近期在开发 Windows 端 Tauri 应用时就踩了这个坑，尝试了网上大部分常规解法都无效，最终通过调整 capabilities 配置解决了问题，本文就完整复盘整个解决过程，希望能帮到遇到同样问题的开发者。

一、问题背景与报错详情

在 Tauri 应用中调用shell.open()方法打开外部 URL（比如https://xxx.com）时，控制台直接抛出如下错误：

Uncaught (in promise) shell.open not allowed URL: allowed on: [windows: "*", URL: local], [windows: "*", URL: local] referenced by: capability: default-capability, permission: allow-open || capability: default-capability, permission: allow-open

从报错信息能看出核心问题：Tauri 的权限策略仅允许打开local（本地）URL，而我要打开的是远程 HTTP/HTTPS 链接，因此被权限拦截了。

二、踩坑：尝试常规解法（均无效）

遇到问题后，我首先查阅了 Tauri 官方文档和网上的常规解决方案，逐一尝试但都没解决问题：

1. 调整 tauri.conf.json 中的 allowlist

按照网上教程，在tauri.conf.json的tauri > allowlist > shell中配置open: true，并尝试增加 URL 白名单：

{
  "tauri": {
    "allowlist": {
      "shell": {
        "open": true,
        "allow": ["https://*", "http://*"] // 尝试添加允许的URL
      }
    }
  }
}

重新构建应用后，报错依然存在。

2. 配置 permissions 数组

有教程提到需要在 allowlist 同级增加permissions配置，我也尝试了：

{
  "tauri": {
    "allowlist": {
      "shell": {
        "open": true
      }
    },
    "permissions": [
      {
        "name": "shell:open",
        "allow": ["https://*", "http://*"]
      }
    ]
  }
}

结果还是一样的报错，问题没有任何改善。

3. 检查 tauri 版本与 API 用法

确认自己使用的 Tauri 版本（v2.x）中shell.open()的调用方式无误：

import { shell } from '@tauri-apps/plugin-shell';

// 调用代码
async function openExternalUrl() {
  try {
    await shell.open('https://www.example.com');
  } catch (e) {
    console.error('打开URL失败：', e);
  }
}

API 用法符合官方文档，排除了调用方式错误的可能。

三、解决：调整 capabilities/default.json 配置

在尝试了所有常规解法都无效后，我注意到 Tauri v2.x 版本中权限管理的核心是capabilities（能力）配置，而非旧版本的 allowlist。最终通过修改src-tauri/capabilities/default.json文件解决了问题：

1. 原始 default.json 配置

默认配置中仅允许本地 URL，没有开放远程 URL 权限：

{
  "$schema": "../gen/schemas/capability-schema.json",
  "identifier": "default-capability",
  "description": "Default capabilities for the app",
  "permissions": [
    {
      "identifier": "allow-open",
      "description": "Allow opening URLs",
      "allow": [
        {
          "shell:open": {
            "windows": "*",
            "url": "local"
          }
        }
      ]
    }
  ]
}

2. 修改后的配置（核心）

在default.json中增加remote节点，开放所有远程 URL 的访问权限（也可根据需求限定具体域名）：

{
  "$schema": "../gen/schemas/capability-schema.json",
  "identifier": "default-capability",
  "description": "Default capabilities for the app",
  "permissions": [
    {
      "identifier": "allow-open",
      "description": "Allow opening URLs",
      "allow": [
        {
          "shell:open": {
            "windows": "*",
            "url": "local"
          }
        },
        {
          "shell:open": {
            "windows": "*",
            "url": "remote"
          }
        }
      ]
    }
  ],
  "remote": {
    "urls": ["https://*", "http://*", "/**"]
  }
}

3. 关键说明

• remote.urls：指定允许访问的远程 URL 范围，https://*和http://*表示允许所有 HTTPS/HTTP 链接，/**兼容本地路径；
• 新增"url": "remote"的shell:open权限，明确允许打开远程 URL；
• 修改后需要重新构建应用 （pnpm tauri build或pnpm tauri dev），配置才能生效。

四、验证：问题解决

修改配置并重启应用后，再次调用shell.open()打开远程 URL，控制台无报错，外部浏览器能正常打开目标链接，问题彻底解决。

总结

1. Tauri v2.x 版本的权限管理核心是capabilities配置，而非旧版本的 allowlist，这是很多开发者踩坑的关键；
2. 解决shell.open not allowed URL报错的核心是在capabilities/default.json中配置remote.urls，并开放shell:open的remote URL 权限；
3. 网上部分教程基于 Tauri v1.x，其中的 allowlist 配置在 v2.x 中已不再生效，需注意版本适配。

如果你的 Tauri 应用也遇到类似的 URL 权限报错，不妨优先检查capabilities配置文件，而非执着于旧版的 allowlist，大概率能快速解决问题。