更新

GitHub npm crates.io

API Reference

自动使用更新服务器或静态 JSON 更新你的 Tauri 应用程序。

Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

Setup

从安装 Tauri 更新插件开始。

自动

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

npm

npm run tauri add updater

yarn

yarn run tauri add updater

pnpm

pnpm tauri add updater

deno

deno task tauri add updater

bun

bun tauri add updater

cargo

cargo tauri add updater

手动

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

   cargo add tauri-plugin-updater --target 'cfg(any(target_os = "macos", windows, target_os = "linux"))'

2. 修改 lib.rs 来初始化插件。

   lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .setup(|app| {
               #[cfg(desktop)]
               app.handle().plugin(tauri_plugin_updater::Builder::new().build());
               Ok(())
           })
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. 使用你喜欢的 JavaScript 包管理器安装 JavaScript Guest 绑定。

   npm

   npm install @tauri-apps/plugin-updater

   yarn

   yarn add @tauri-apps/plugin-updater

   pnpm

   pnpm add @tauri-apps/plugin-updater

   deno

   deno add npm:@tauri-apps/plugin-updater

   bun

   bun add @tauri-apps/plugin-updater

签名更新包

Tauri 的更新程序需要签名来验证更新来自可信来源。这不能被禁用。

要对更新进行签名，你需要两个密钥：

1. 公钥将在 tauri.conf.json 中设置，以便在安装前验证升级包。只要您的私钥是安全的，此公钥就可以安全地上传和共享。
2. 私钥，用于为安装程序文件签名。你不应该与任何人共享这把钥匙。此外，如果你丢失了这个密钥，你将无法向已经安装应用程序的用户发布新的更新。把这个密钥放在安全的地方很重要！

为了生成密钥，Tauri CLI 提供了 signer generate 命令。你可以运行以下命令在主文件夹中创建密钥。

npm

npm run tauri signer generate -- -w ~/.tauri/myapp.key

yarn

yarn tauri signer generate -w ~/.tauri/myapp.key

pnpm

pnpm tauri signer generate -w ~/.tauri/myapp.key

deno

deno task tauri signer generate -w ~/.tauri/myapp.key

bun

bunx tauri signer generate -w ~/.tauri/myapp.key

cargo

cargo tauri signer generate -w ~/.tauri/myapp.key

构建

在构建您的更新包时，您需要在环境变量中配置上述生成的私钥。.env 文件不起作用！

Mac/Linux

export TAURI_SIGNING_PRIVATE_KEY="Path or content of your private key"
# optionally also add a password
export TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""

Windows

在 PowerShell 中运行。

$env:TAURI_SIGNING_PRIVATE_KEY="Path or content of your private key"
<# optionally also add a password #>
$env:TAURI_SIGNING_PRIVATE_KEY_PASSWORD=""

之后，您可以像往常一样运行 Tauri build，Tauri 将生成更新包及其签名。 生成的文件依赖于下面配置的 createUpdaterArtifacts 配置值。

v2

{
  "bundle": {
    "createUpdaterArtifacts": true
  }
}

在 Linux 上，Tauri 将在 target/release/bundle/appimage/ 文件夹中创建 AppImage。

• myapp.AppImage - 标准的应用程序包。它将被更新者重新使用。
• myapp.AppImage.sig - 更新包的签名。

在 macOS 系统上，Tauri 会从 target/release/bundle/macos/ 文件夹内的应用程序包创建一个 .tar.gz 归档文件。

• myapp.app - 标准的应用程序包。
• myapp.app.tar.gz - 更新包。
• myapp.app.tar.gz.sig - 更新包的签名。

在 Windows 系统上，Tauri 会在 target/release/bundle/msi/ and target/release/bundle/nsis 文件夹内创建常规的 MSI 和 NSIS 安装程序。

• myapp-setup.exe - 标准的应用程序包。它将被更新者重新使用。
• myapp-setup.exe.sig - 更新包的签名。
• myapp.msi - 标准的应用程序包。它将被更新者重新使用。
• myapp.msi.sig - 更新包的签名。

v1 compatible

{
  "bundle": {
    "createUpdaterArtifacts": "v1Compatible"
  }
}

在 Linux 上，Tauri 将在 target/release/bundle/appimage/ 文件夹中创建 AppImage。

• myapp.AppImage - 标准的应用包。
• myapp.AppImage.tar.gz - 更新包。
• myapp.AppImage.tar.gz.sig - 更新包的签名。

在 macOS 系统上，Tauri 会从 target/release/bundle/macos/ 文件夹内的应用程序包创建一个 .tar.gz 归档文件。

• myapp.app - 标准的应用包。
• myapp.app.tar.gz - 更新包。
• myapp.app.tar.gz.sig - 更新包的签名。

在 Windows 系统上，Tauri 会从 target/release/bundle/msi/ 和 target/release/bundle/nsis 文件夹内的 MSI 和 NSIS 安装程序创建 .zip 归档文件。

• myapp-setup.exe - 标准的应用包。
• myapp-setup.nsis.zip - 更新包。
• myapp-setup.nsis.zip.sig - 更新包的签名。
• myapp.msi - 标准的应用包。
• myapp.msi.zip - 更新包。
• myapp.msi.zip.sig - 更新包的签名。

Tauri 配置

以这种格式设置 tauri.conf.json，以使更新程序开始工作。

Keys	Description
createUpdaterArtifacts	将其设置为 true 告诉 Tauri 的应用打包器创建更新包。如果你要从较旧的 Tauri 版本迁移应用程序，请将其设置为 "v1Compatible"。此设置将在 v3 中删除，所以一旦所有用户迁移到 v2，请确保将其更改为 true。
pubkey	这必须是上面步骤中从 Tauri CLI 生成的公钥。它不能是文件路径！
endpoints	这必须是一个字符串形式的 url 数组。TLS 在生产模式下强制执行。只有返回非 2xx 状态码时，Tauri 才会继续访问下一个 url！
dangerousInsecureTransportProtocol	将其设置为 true 允许更新器接受非 https 端点。请谨慎使用此配置！

每个更新的 URL 可以包含以下动态变量，允许您在服务器端确定更新是否可用。

• {{current_version}}：请求更新的应用程序版本。
• {{target}}：操作系统名称 （linux、windows 或 darwin 之一）。
• {{arch}}：机器的架构 （x86_64、i686、aarch64 或 armv7 之一）。

tauri.conf.json

{
  "bundle": {
    "createUpdaterArtifacts": true
  },
  "plugins": {
    "updater": {
      "pubkey": "CONTENT FROM PUBLICKEY.PEM",
      "endpoints": [
        "https://releases.myapp.com/{{target}}/{{arch}}/{{current_version}}",
        // or a static github json file
        "https://github.com/user/repo/releases/latest/download/latest.json"
      ]
    }
  }
}

提示

不支持自定义变量，但可以定义自定义 {{target}}。

installMode on Windows

在 Windows 平台上，有一个额外的可选的 "installMode" 配置来更改更新包的安装方式。

tauri.conf.json

{
  "plugins": {
    "updater": {
      "windows": {
        "installMode": "passive"
      }
    }
  }
}

• "passive"：会有一个带有进度条的小窗口。该更新将在不需要任何用户交互的情况下安装。一般推荐使用默认模式。
• "basicUi"：将显示一个基本的用户界面，它需要用户交互来完成安装。
• "quiet"：没有进度反馈给用户。在这种模式下，安装程序不能自行请求管理员权限，所以它只适用于用户范围内的安装，或者当您的应用程序本身已经以管理员权限运行时。一般不推荐。

服务器的支持

更新插件可以以两种方式使用。要么使用动态更新服务器，要么使用静态 JSON 文件（用于 S3 或 GitHub gist 等服务）。

静态 JSON 文件

使用静态文件时，只需要返回一个包含所需信息的 JSON。

Keys	Description
version	必须是一个有效的 SemVer，带或不带 v，这意味着 1.0.0 和 v1.0.0 都是有效的。
notes	更新说明。
pub_date	如果存在日期，则必须按照 RFC 3339 规范格式化。
platforms	每个平台的字段名都是 OS-ARCH 格式，其中 OS 是 linux、darwin 或 windows 中的一个，而 ARCH 是 x86_64、aarch64、i686 或 armv7 中的一个。
signature	生成的 .sig 文件的内容，可能会随着每次构建而改变。路径或 URL 将不起作用！

当使用自定义目标时，所提供的目标字符串会与 platforms 键进行匹配，而非默认的 OS-ARCH 值。

"version"、"platforms.[target].url" 和 "platforms.[target].signature" 是必需的；其它字段是可选的。

{
  "version": "",
  "notes": "",
  "pub_date": "",
  "platforms": {
    "linux-x86_64": {
      "signature": "",
      "url": ""
    },
    "windows-x86_64": {
      "signature": "",
      "url": ""
    },
    "darwin-x86_64": {
      "signature": "",
      "url": ""
    }
  }
}

注意，Tauri 将在检查 version 字段之前验证整个文件，因此请确保所有现有平台配置都是有效和完整的。

提示

Tauri Action 会生成一个静态的 JSON 文件供你在 cdn 上使用，比如 GitHub 发行版。

动态更新服务器

在使用动态更新服务器时，Tauri 会遵循服务器的指令。若要禁用内部版本检查，您可以覆盖 Tauri 的版本比较，这样就会安装服务器发送的版本（如果您需要回滚应用程序，这很有用）。

您的服务器可以使用上述 endpoint URL 中定义的变量来确定是否需要更新。如果您需要更多数据，可以根据自己的喜好在 Rust 中添加额外的请求头。

如果没有可用的更新，您的服务器应响应状态码为 204 无内容。

如果需要更新，您的服务器应使用状态码 200 OK 进行响应，并以这种格式提供 JSON 响应。

Keys	Description
version	必须是一个有效的 SemVer，带或不带 v，这意味着 1.0.0 和 v1.0.0 都是有效的。
notes	更新说明。
pub_date	如果存在日期，则必须按照 RFC 3339 规范格式化。
url	这必须是的有效更新包 URL。
signature	生成的 .sig 文件的内容，可能会随着每次构建而改变。路径或 URL 将不起作用！

"url"、"version" and "signature" 是必须的；其它字段是可选的。

{
  "version": "",
  "pub_date": "",
  "url": "",
  "signature": "",
  "notes": ""
}

提示

金牛座的官方合作伙伴 CrabNebula 提供了一个动态更新服务器。有关更多信息，请参阅 Distributing with CrabNebula Cloud 文档。

检查更新

用于检查和安装更新的默认 API 利用配置的端点，可以由 JavaScript 和 Rust 代码访问。

JavaScript

import { check } from '@tauri-apps/plugin-updater';
import { relaunch } from '@tauri-apps/plugin-process';

const update = await check();
if (update) {
  console.log(
    `found update ${update.version} from ${update.date} with notes ${update.body}`
  );
  let downloaded = 0;
  let contentLength = 0;
  // alternatively we could also call update.download() and update.install() separately
  await update.downloadAndInstall((event) => {
    switch (event.event) {
      case 'Started':
        contentLength = event.data.contentLength;
        console.log(`started downloading ${event.data.contentLength} bytes`);
        break;
      case 'Progress':
        downloaded += event.data.chunkLength;
        console.log(`downloaded ${downloaded} from ${contentLength}`);
        break;
      case 'Finished':
        console.log('download finished');
        break;
    }
  });

  console.log('update installed');
  await relaunch();
}

更多有关信息，请参阅 JavaScript API 文档。

Rust

src-tauri/src/lib.rs

use tauri_plugin_updater::UpdaterExt;

pub fn run() {
  tauri::Builder::default()
    .setup(|app| {
      let handle = app.handle().clone();
      tauri::async_runtime::spawn(async move {
        update(handle).await.unwrap();
      });
      Ok(())
    })
    .run(tauri::generate_context!())
    .unwrap();
}

async fn update(app: tauri::AppHandle) -> tauri_plugin_updater::Result<()> {
  if let Some(update) = app.updater()?.check().await? {
    let mut downloaded = 0;

    // alternatively we could also call update.download() and update.install() separately
    update
      .download_and_install(
        |chunk_length, content_length| {
          downloaded += chunk_length;
          println!("downloaded {downloaded} from {content_length:?}");
        },
        || {
          println!("download finished");
        },
      )
      .await?;

    println!("update installed");
    app.restart();
  }

  Ok(())
}

提示

要通知前端下载进度，请考虑使用带 channel 的命令。

Updater command

#[cfg(desktop)]
mod app_updates {
    use std::sync::Mutex;
    use serde::Serialize;
    use tauri::{ipc::Channel, AppHandle, State};
    use tauri_plugin_updater::{Update, UpdaterExt};

    #[derive(Debug, thiserror::Error)]
    pub enum Error {
        #[error(transparent)]
        Updater(#[from] tauri_plugin_updater::Error),
        #[error("there is no pending update")]
        NoPendingUpdate,
    }

    impl Serialize for Error {
        fn serialize<S>(&self, serializer: S) -> std::result::Result<S::Ok, S::Error>
        where
            S: serde::Serializer,
        {
            serializer.serialize_str(self.to_string().as_str())
        }
    }

    type Result<T> = std::result::Result<T, Error>;

    #[derive(Clone, Serialize)]
    #[serde(tag = "event", content = "data")]
    pub enum DownloadEvent {
        #[serde(rename_all = "camelCase")]
        Started {
            content_length: Option<u64>,
        },
        #[serde(rename_all = "camelCase")]
        Progress {
            chunk_length: usize,
        },
        Finished,
    }

    #[derive(Serialize)]
    #[serde(rename_all = "camelCase")]
    pub struct UpdateMetadata {
        version: String,
        current_version: String,
    }

    #[tauri::command]
    pub async fn fetch_update(
        app: AppHandle,
        pending_update: State<'_, PendingUpdate>,
    ) -> Result<Option<UpdateMetadata>> {
        let channel = "stable";
        let url = url::Url::parse(&format!(
            "https://cdn.myupdater.com/{{{{target}}}}-{{{{arch}}}}/{{{{current_version}}}}?channel={channel}",
        )).expect("invalid URL");

      let update = app
          .updater_builder()
          .endpoints(vec![url])?
          .build()?
          .check()
          .await?;

      let update_metadata = update.as_ref().map(|update| UpdateMetadata {
          version: update.version.clone(),
          current_version: update.current_version.clone(),
      });

      *pending_update.0.lock().unwrap() = update;

      Ok(update_metadata)
    }

    #[tauri::command]
    pub async fn install_update(pending_update: State<'_, PendingUpdate>, on_event: Channel<DownloadEvent>) -> Result<()> {
        let Some(update) = pending_update.0.lock().unwrap().take() else {
            return Err(Error::NoPendingUpdate);
        };

        let started = false;

        update
            .download_and_install(
                |chunk_length, content_length| {
                    if !started {
                        let _ = on_event.send(DownloadEvent::Started { content_length });
                        started = true;
                    }

                    let _ = on_event.send(DownloadEvent::Progress { chunk_length });
                },
                || {
                    let _ = on_event.send(DownloadEvent::Finished);
                },
            )
            .await?;

        Ok(())
    }

    struct PendingUpdate(Mutex<Option<Update>>);
}

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_process::init())
        .setup(|app| {
            #[cfg(desktop)]
            {
                app.handle().plugin(tauri_plugin_updater::Builder::new().build());
                app.manage(app_updates::PendingUpdate(Mutex::new(None)));
            }
            Ok(())
        })
        .invoke_handler(tauri::generate_handler![
            #[cfg(desktop)]
            app_updates::fetch_update,
            #[cfg(desktop)]
            app_updates::install_update
        ])
}

更多有关信息，请参阅 Rust API 文档。

请注意，安装更新后不需要立即重启应用程序，你可以选择如何处理更新，要么等待用户手动重启应用程序，要么提示他选择何时这样做。

注意

在 Windows 上，由于 Windows 安装程序的限制，应用程序在执行安装步骤时将自动退出。

当检查和下载更新时，可以定义自定义的请求超时、代理和请求头。

JavaScript

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

const update = await check({
  proxy: '<proxy url>',
  timeout: 30000 /* milliseconds */,
  headers: {
    Authorization: 'Bearer <token>',
  },
});

Rust

use tauri_plugin_updater::UpdaterExt;
let update = app
  .updater_builder()
  .timeout(std::time::Duration::from_secs(30))
  .proxy("<proxy-url>".parse().expect("invalid URL"))
  .header("Authorization", "Bearer <token>")
  .build()?
  .check()
  .await?;

运行时配置

更新 api 还允许在运行时配置更新程序，以获得更大的灵活性。 出于安全原因，一些 api 仅对 Rust 可用。

Endpoints

设置运行时检查更新的 url 可以允许更多的动态更新，例如单独的发布通道：

use tauri_plugin_updater::UpdaterExt;
let channel = if beta { "beta" } else { "stable" };
let update_url = format!("https://{channel}.myserver.com/{{{{target}}}}-{{{{arch}}}}/{{{{current_version}}}}");

let update = app
  .updater_builder()
  .endpoints(vec![update_url])?
  .build()?
  .check()
  .await?;

提示

注意，使用 format!() 来插入更新 URL 时，需要对变量进行双重转义， 例如 {{{{target}}}}。

公钥

在运行时设置公钥对于实现密钥轮换逻辑可能很有用。 它可以由插件构建器或更新器构建器设置：

tauri_plugin_updater::Builder::new().pubkey("<your public key>").build()

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .pubkey("<your public key>")
  .build()?
  .check()
  .await?;

自定义目标

默认情况下，更新程序允许您使用 {{target}} and {{arch}} 变量来确定必须交付哪个更新资产。 如果您需要有关更新的更多信息（例如，在分发通用 macOS 二进制选项或有更多构建风格时），您可以设置自定义目标。

JavaScript

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

const update = await check({
  target: 'macos-universal',
});

Rust

自定义目标可以由插件构建者或更新器构建者来设置。

tauri_plugin_updater::Builder::new().target("macos-universal").build()

use tauri_plugin_updater::UpdaterExt;
let update = app
  .updater_builder()
  .target("macos-universal")
  .build()?
  .check()
  .await?;

提示

默认的 $target-$arch 键可以使用 tauri_plugin_updater::target() 来获取，该函数返回一个 Option<String>，当当前平台不支持更新器时，其值为 None。

注意

• 当使用自定义目标时，可能更容易使用它来确定更新平台，所以你可以删除 {{arch}} 变量。
• 所提供的目标值是在使用静态 JSON 文件时与平台键相匹配的键。

允许降级

默认情况下，Tauri 会检查更新版本是否大于当前应用程序版本，以验证是否应该更新。 为了允许降级，你必须使用更新构建器的 version_comparator API。

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .version_comparator(|current, update| {
    // default comparison: `update.version > current`
    update.version != current
  })
  .build()?
  .check()
  .await?;

窗口退出前的钩子函数

由于 Windows 安装程序的限制，Tauri 会在 Windows 上安装更新之前自动退出您的应用程序。 要在此之前执行操作，请使用 on_before_exit 函数。

use tauri_plugin_updater::UpdaterExt;

let update = app
  .updater_builder()
  .on_before_exit(|| {
    println!("app is about to exit on Windows!");
  })
  .build()?
  .check()
  .await?;

注意

如果没有设置任何构建器的值，则使用配置中的值作为备用。

权限

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

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

src-tauri/capabilities/default.json

{
  "permissions": [
    ...,
    "updater:default",
  ]
}

Default Permission

This permission set configures which kind of updater functions are exposed to the frontend.

Granted Permissions

The full workflow from checking for updates to installing them is enabled.

• allow-check
• allow-download
• allow-install
• allow-download-and-install

Permission Table

Identifier	Description
updater:allow-check	Enables the check command without any pre-configured scope.
updater:deny-check	Denies the check command without any pre-configured scope.
updater:allow-download	Enables the download command without any pre-configured scope.
updater:deny-download	Denies the download command without any pre-configured scope.
updater:allow-download-and-install	Enables the download_and_install command without any pre-configured scope.
updater:deny-download-and-install	Denies the download_and_install command without any pre-configured scope.
updater:allow-install	Enables the install command without any pre-configured scope.
updater:deny-install	Denies the install command without any pre-configured scope.