Skip to content
Tauri 中文网
开发指南 参考手册 当前版本 v2.2

更新程序

GitHub npm crates.io
API Reference

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

¥Automatically update your Tauri app with an update server or a static JSON.

支持的平台

¥Supported Platforms

This plugin requires a Rust version of at least 1.77.2

Platform Level Notes
windows
linux
macos
android
ios

设置

¥Setup

安装 Tauri 更新程序插件以开始使用。

¥Install the Tauri updater plugin to get started.

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

¥Use your project’s package manager to add the dependency:

npm run tauri add updater

签名更新

¥Signing updates

Tauri 的更新程序需要签名来验证更新是否来自可信来源。无法禁用此功能。

¥Tauri’s updater needs a signature to verify that the update is from a trusted source. This cannot be disabled.

要签署更新，你需要两个密钥：

¥To sign your updates you need two keys:

  1. 公钥，将在 tauri.conf.json 中设置以在安装前验证工件。只要你的私钥是安全的，就可以安全地上传和共享此公钥。

    ¥The public key, which will be set in the tauri.conf.json to validate the artifacts before the installation. This public key can be uploaded and shared safely as long as your private key is secure.

  2. 私钥，用于签署安装程序文件。你永远不应该与任何人共享此密钥。此外，如果你丢失了此密钥，你将无法向已安装该应用的用户发布新更新。将此密钥存储在安全的地方很重要！

    ¥The private key, which is used to sign your installer files. You should NEVER share this key with anyone. Also, if you lose this key you will NOT be able to publish new updates to the users that have the app already installed. It is important to store this key in a safe place!

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

¥To generate the keys the Tauri CLI provides the signer generate command. You can run this to create the keys in the home folder:

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

构建

¥Building

在构建更新工件时，你需要在环境变量中拥有上面生成的私钥。.env 文件不起作用！

¥While building your update artifacts, you need to have the private key you generated above in your environment variables. .env files do not work!

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

之后，你可以照常运行 Tauri 构建，Tauri 将生成更新包及其签名。生成的文件取决于下面配置的 createUpdaterArtifacts 配置值。

¥After that, you can run Tauri build as usual and Tauri will generate the update bundles and their signatures. The generated files depend on the createUpdaterArtifacts configuration value configured below.

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

在 Linux 上，Tauri 将在 target/release/bundle/appimage/ 文件夹中创建普通的 AppImage：

¥On Linux, Tauri will create the normal AppImage inside the target/release/bundle/appimage/ folder:

  • myapp.AppImage - 标准应用包。它将被更新程序重复使用。

    ¥myapp.AppImage - The standard app bundle. It will be re-used by the updater.

  • myapp.AppImage.sig - 更新程序包的签名。

    ¥myapp.AppImage.sig - The signature of the updater bundle.

在 macOS 上，Tauri 将从 target/release/bundle/macos/ 文件夹中的应用包中创建一个 .tar.gz 存档：

¥On macOS, Tauri will create a .tar.gz archive from the application bundle inside the target/release/bundle/macos/ folder:

  • myapp.app - 标准应用包。

    ¥myapp.app - The standard app bundle.

  • myapp.app.tar.gz - 更新程序包。

    ¥myapp.app.tar.gz - The updater bundle.

  • myapp.app.tar.gz.sig - 更新包的签名。

    ¥myapp.app.tar.gz.sig - The signature of the update bundle.

在 Windows 上，Tauri 将在 target/release/bundle/msi/ 和 target/release/bundle/nsis 文件夹内创建常规 MSI 和 NSIS 安装程序：

¥On Windows, Tauri will create the normal MSI and NSIS installers inside the target/release/bundle/msi/ and target/release/bundle/nsis folders:

  • myapp-setup.exe - 标准应用包。它将被更新程序重复使用。

    ¥myapp-setup.exe - The standard app bundle. It will be re-used by the updater.

  • myapp-setup.exe.sig - 更新包的签名。

    ¥myapp-setup.exe.sig - The signature of the update bundle.

  • myapp.msi - 标准应用包。它将被更新程序重复使用。

    ¥myapp.msi - The standard app bundle. It will be re-used by the updater.

  • myapp.msi.sig - 更新包的签名。

    ¥myapp.msi.sig - The signature of the update bundle.

Tauri 配置

¥Tauri Configuration

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

¥Set up the tauri.conf.json in this format for the updater to start working.

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

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

¥Each updater URL can contain the following dynamic variables, allowing you to determine server-side if an update is available.

  • {{current_version}}：请求更新的应用的版本。

    ¥{{current_version}}: The version of the app that is requesting the update.

  • {{target}}：操作系统名称（linux、windows 或 darwin 之一）。

    ¥{{target}}: The operating system name (one of linux, windows or darwin).

  • {{arch}}：机器的架构（x86_64、i686、aarch64 或 armv7 之一）。

    ¥{{arch}}: The architecture of the machine (one of x86_64, i686, aarch64 or 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"
      ]
    }
  }
}

:::tip 提示

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

¥Custom variables are not supported, but you can define a custom {{target}}.

:::

Windows 上的 installMode

¥installMode on Windows

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

¥On Windows there is an additional optional "installMode" config to change how the update is installed.

tauri.conf.json
{
  "plugins": {
    "updater": {
      "windows": {
        "installMode": "passive"
      }
    }
  }
}

  • "passive"：将有一个带有进度条的小窗口。无需任何用户交互即可安装更新。通常推荐和默认模式。

    ¥"passive": There will be a small window with a progress bar. The update will be installed without requiring any user interaction. Generally recommended and the default mode.

  • "basicUi"：将显示一个基本用户界面，需要用户交互才能完成安装。

    ¥"basicUi": There will be a basic user interface shown which requires user interaction to finish the installation.

  • "quiet"：不会向用户提供进度反馈。使用此模式，安装程序无法自行请求管理员权限，因此它仅在用户范围的安装中或你的应用本身已经以管理员权限运行时才有效。一般不推荐。

    ¥"quiet": There will be no progress feedback to the user. With this mode the installer cannot request admin privileges by itself so it only works in user-wide installations or when your app itself already runs with admin privileges. Generally not recommended.

服务器支持

¥Server Support

更新程序插件有两种使用方式。使用动态更新服务器或静态 JSON 文件（用于 S3 或 GitHub gists 等服务）。

¥The updater plugin can be used in two ways. Either with a dynamic update server or a static JSON file (to use on services like S3 or GitHub gists).

静态 JSON 文件

¥Static JSON File

当使用静态时，你只需返回包含所需信息的 JSON。

¥When using static, you just need to return a JSON containing the required information.

密钥描述
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 不起作用！

:::info 信息

使用 自定义目标 时，提供的目标字符串与 platforms 键匹配，而不是与默认的 OS-ARCH 值匹配。

¥When using custom targets the provided target string is matched against the platforms key instead of the default OS-ARCH value.

:::

所需的键是 "version"、"platforms.[target].url" 和 "platforms.[target].signature"；其他内容是可选的。

¥The required keys are "version", "platforms.[target].url" and "platforms.[target].signature"; the others are optional.

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

请注意，Tauri 将在检查版本字段之前验证整个文件，因此请确保所有现有平台配置均有效且完整。

¥Note that Tauri will validate the whole file before checking the version field, so make sure all existing platform configurations are valid and complete.

:::tip 提示

Tauri Action 生成一个静态 JSON 文件供你在 CDN（例如 GitHub Releases）上使用。

¥Tauri Action generates a static JSON file for you to use on CDNs such as GitHub Releases.

:::

动态更新服务器

¥Dynamic Update Server

当使用动态更新服务器时，Tauri 将遵循服务器的说明。要禁用内部版本检查，你可以覆盖 插件的版本比较，这将安装服务器发送的版本（如果你需要回滚应用，这将很有用）。

¥When using a dynamic update server, Tauri will follow the server’s instructions. To disable the internal version check you can overwrite the plugin’s version comparison, this will install the version sent by the server (useful if you need to roll back your app).

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

¥Your server can use variables defined in the endpoint URL above to determine if an update is required. If you need more data, you can include additional request headers in Rust to your liking.

如果没有可用的更新，你的服务器应该以状态代码 204 No Content 进行响应。

¥Your server should respond with a status code of 204 No Content if there is no update available.

如果需要更新，你的服务器应使用状态代码 200 OK 和以下格式的 JSON 响应进行响应：

¥If an update is required, your server should respond with a status code of 200 OK and a JSON response in this format:

密钥描述
version这必须是有效的 SemVer，带或不带前导 v，这意味着 1.0.0 和 v1.0.0 都是有效的。
notes更新说明。
pub_date如果存在，日期必须根据 RFC 3339 进行格式化。
url这必须是更新包的有效 URL。
signature生成的 .sig 文件的内容，每次构建时可能会发生变化。路径或 URL 不起作用！

所需的键是 "url"、"version" 和 "signature"；其他内容是可选的。

¥The required keys are "url", "version" and "signature"; the others are optional.

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

:::tip 提示

CrabNebula 是 Tauri 的官方合作伙伴，提供动态更新服务器。有关更多信息，请参阅 使用 CrabNebula Cloud 分发 文档。

¥CrabNebula, an official Tauri partner, offers a dynamic update server. For more information, see the Distributing with CrabNebula Cloud documentation.

:::

检查更新

¥Checking for Updates

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

¥The default API for checking updates and installing them leverages the configured endpoints and can be accessed by both JavaScript and Rust code.

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 文档。

¥For more information see the JavaScript API documentation.

请注意，安装更新后无需立即重新启动应用，你可以选择如何处理更新，方法是等待用户手动重新启动应用，或提示他选择何时重新启动。

¥Note that restarting your app immediately after installing an update is not required and you can choose how to handle the update by either waiting until the user manually restarts the app, or prompting him to select when to do so.

:::note 注意

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

¥On Windows the application is automatically exited when the install step is executed due to a limitation of Windows installers.

:::

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

¥When checking and downloading updates it is possible to define a custom request timeout, a proxy and request headers.

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


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

运行时配置

¥Runtime Configuration

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

¥The updater APIs also allows the updater to be configured at runtime for more flexibility. For security reasons some APIs are only available for Rust.

端点

¥Endpoints

设置在运行时检查更新时应请求的 URL 允许更动态的更新，例如单独的发布渠道：

¥Setting the URLs that should be requested to check updates at runtime allows more dynamic updates such as separate release channels:

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?;

:::tip 提示

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

¥Note that when using format!() to interpolate the update URL you need double escapes for the variables e.g. {{{{target}}}}.

:::

公共键

¥Public key

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

¥Setting the public key at runtime can be useful to implement a key rotation logic. It can be set by either the plugin builder or updater builder:

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?;

自定义目标

¥Custom target

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

¥By default the updater lets you use the {{target}} and {{arch}} variables to determine which update asset must be delivered. If you need more information on your updates (e.g. when distributing a Universal macOS binary option or having more build flavors) you can set a custom target.

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


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

:::note 注意

  • 当使用自定义目标时，可能更容易专门使用它来确定更新平台，因此你可以删除 {{arch}} 变量。

    ¥When using a custom target it might be easier to use it exclusively to determine the update platform, so you could remove the {{arch}} variable.

  • 作为目标提供的值是使用 静态 JSON 文件 时与平台密钥匹配的密钥。

    ¥The value provided as target is the key that is matched against the platform key when using a Static JSON file.

:::

允许降级

¥Allowing downgrades

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

¥By default Tauri checks if the update version is greater than the current app version to verify if it should update or not. To allow downgrades, you must use the updater builder’s 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

¥Windows before exit hook

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

¥Due to a limitation of Windows installers, Tauri will automatically quit your application before installing updates on Windows. To perform an action before that happens, use the on_before_exit function:

use tauri_plugin_updater::UpdaterExt;


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

:::note 注意

如果未设置任何构建器值，则使用 configuration 中的值作为后备。

¥The values from the configuration are used as fallback if any of the builder values are not set.

:::

权限

¥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
{
  "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.

Tauri 中文网 - 粤ICP备13048890号