Back to Details

configuring-tauri-apps

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tauri Configuration Files

Tauri 配置文件

Tauri v2 applications use three primary configuration files to manage application behavior, dependencies, and build processes.
Tauri v2 应用使用三个主要配置文件来管理应用行为、依赖项和构建流程。

Configuration File Overview

配置文件概述

FilePurposeFormat
tauri.conf.json
Tauri-specific settingsJSON, JSON5, or TOML
Cargo.toml
Rust dependencies and metadataTOML
package.json
Frontend dependencies and scriptsJSON
文件用途格式
tauri.conf.json
Tauri专属设置JSON、JSON5 或 TOML
Cargo.toml
Rust依赖项和元数据TOML
package.json
前端依赖项和脚本JSON

tauri.conf.json

tauri.conf.json

The main configuration file located in 
src-tauri/
. Defines application metadata, window behavior, bundling options, and plugin settings.
位于 
src-tauri/
下的主配置文件，用于定义应用元数据、窗口行为、打包选项和插件设置。

Supported Formats

支持的格式

  • JSON (default): 
    tauri.conf.json
  • JSON5: 
    tauri.conf.json5
    (requires 
    config-json5
    Cargo feature)
  • TOML: 
    Tauri.toml
    (requires 
    config-toml
    Cargo feature)
  • JSON（默认）：
    tauri.conf.json
  • JSON5：
    tauri.conf.json5
    （需要启用 
    config-json5
    Cargo 特性）
  • TOML：
    Tauri.toml
    （需要启用 
    config-toml
    Cargo 特性）

Complete Configuration Structure

完整配置结构

json
{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "MyApp",
  "version": "1.0.0",
  "identifier": "com.company.myapp",
  "mainBinaryName": "my-app",
  "build": {
    "devUrl": "http://localhost:3000",
    "frontendDist": "../dist",
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "features": ["custom-feature"],
    "removeUnusedCommands": true
  },
  "app": {
    "withGlobalTauri": false,
    "macOSPrivateApi": false,
    "windows": [
      {
        "title": "My Application",
        "width": 1200,
        "height": 800,
        "minWidth": 800,
        "minHeight": 600,
        "resizable": true,
        "fullscreen": false,
        "center": true,
        "visible": true,
        "decorations": true,
        "transparent": false,
        "alwaysOnTop": false,
        "focus": true,
        "url": "index.html"
      }
    ],
    "security": {
      "capabilities": [],
      "assetProtocol": {
        "enable": true,
        "scope": ["$APPDATA/**"]
      },
      "pattern": { "use": "brownfield" },
      "freezePrototype": false
    },
    "trayIcon": {
      "id": "main-tray",
      "iconPath": "icons/tray.png",
      "iconAsTemplate": true
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"],
    "resources": ["assets/**/*"],
    "copyright": "Copyright 2024",
    "category": "Utility",
    "shortDescription": "A short app description",
    "longDescription": "A longer description",
    "licenseFile": "../LICENSE",
    "windows": {
      "certificateThumbprint": null,
      "timestampUrl": "http://timestamp.digicert.com",
      "nsis": { "license": "../LICENSE", "installerIcon": "icons/icon.ico", "installMode": "currentUser" }
    },
    "macOS": {
      "minimumSystemVersion": "10.13",
      "signingIdentity": null,
      "dmg": { "appPosition": { "x": 180, "y": 170 }, "applicationFolderPosition": { "x": 480, "y": 170 } }
    },
    "linux": {
      "appimage": { "bundleMediaFramework": false },
      "deb": { "depends": ["libwebkit2gtk-4.1-0"] },
      "rpm": { "depends": ["webkit2gtk4.1"] }
    },
    "android": { "minSdkVersion": 24 },
    "iOS": { "minimumSystemVersion": "13.0" }
  },
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY",
      "endpoints": ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"]
    }
  }
}
json
{
  "$schema": "https://schema.tauri.app/config/2",
  "productName": "MyApp",
  "version": "1.0.0",
  "identifier": "com.company.myapp",
  "mainBinaryName": "my-app",
  "build": {
    "devUrl": "http://localhost:3000",
    "frontendDist": "../dist",
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build",
    "features": ["custom-feature"],
    "removeUnusedCommands": true
  },
  "app": {
    "withGlobalTauri": false,
    "macOSPrivateApi": false,
    "windows": [
      {
        "title": "My Application",
        "width": 1200,
        "height": 800,
        "minWidth": 800,
        "minHeight": 600,
        "resizable": true,
        "fullscreen": false,
        "center": true,
        "visible": true,
        "decorations": true,
        "transparent": false,
        "alwaysOnTop": false,
        "focus": true,
        "url": "index.html"
      }
    ],
    "security": {
      "capabilities": [],
      "assetProtocol": {
        "enable": true,
        "scope": ["$APPDATA/**"]
      },
      "pattern": { "use": "brownfield" },
      "freezePrototype": false
    },
    "trayIcon": {
      "id": "main-tray",
      "iconPath": "icons/tray.png",
      "iconAsTemplate": true
    }
  },
  "bundle": {
    "active": true,
    "targets": "all",
    "icon": ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"],
    "resources": ["assets/**/*"],
    "copyright": "Copyright 2024",
    "category": "Utility",
    "shortDescription": "A short app description",
    "longDescription": "A longer description",
    "licenseFile": "../LICENSE",
    "windows": {
      "certificateThumbprint": null,
      "timestampUrl": "http://timestamp.digicert.com",
      "nsis": { "license": "../LICENSE", "installerIcon": "icons/icon.ico", "installMode": "currentUser" }
    },
    "macOS": {
      "minimumSystemVersion": "10.13",
      "signingIdentity": null,
      "dmg": { "appPosition": { "x": 180, "y": 170 }, "applicationFolderPosition": { "x": 480, "y": 170 } }
    },
    "linux": {
      "appimage": { "bundleMediaFramework": false },
      "deb": { "depends": ["libwebkit2gtk-4.1-0"] },
      "rpm": { "depends": ["webkit2gtk4.1"] }
    },
    "android": { "minSdkVersion": 24 },
    "iOS": { "minimumSystemVersion": "13.0" }
  },
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY",
      "endpoints": ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"]
    }
  }
}

Root-Level Fields

根级字段

FieldTypeRequiredDescription
productName
stringNoApplication display name
version
stringNoSemver version or path to package.json
identifier
stringYesReverse domain identifier (e.g., 
com.tauri.example
)
mainBinaryName
stringNoOverride the main binary filename
字段类型是否必填描述
productName
字符串否应用显示名称
version
字符串否Semver 版本号或指向 package.json 的路径
identifier
字符串是反向域名标识符（例如 
com.tauri.example
）
mainBinaryName
字符串否覆盖主二进制文件名

Build Configuration Fields

构建配置字段

FieldTypeDescription
devUrl
stringDevelopment server URL for hot-reload
frontendDist
stringPath to built frontend assets or remote URL
beforeDevCommand
stringScript to run before 
tauri dev
beforeBuildCommand
stringScript to run before 
tauri build
features
string[]Cargo features to enable during build
removeUnusedCommands
booleanStrip unused plugin commands from binary
字段类型描述
devUrl
字符串用于热重载的开发服务器URL
frontendDist
字符串已构建前端资源的路径或远程URL
beforeDevCommand
字符串运行 
tauri dev
前执行的脚本
beforeBuildCommand
字符串运行 
tauri build
前执行的脚本
features
字符串数组构建期间启用的Cargo特性
removeUnusedCommands
布尔值从二进制文件中剥离未使用的插件命令

Window Configuration Options

窗口配置选项

FieldTypeDefaultDescription
title
string
"Tauri"
Window title
width
/ 
height
number
800
/ 
600
Window dimensions in pixels
minWidth
/ 
minHeight
number-Minimum dimensions
maxWidth
/ 
maxHeight
number-Maximum dimensions
x
/ 
y
number-Window position
resizable
boolean
true
Allow window resizing
fullscreen
boolean
false
Start in fullscreen
center
boolean
false
Center window on screen
visible
boolean
true
Window visibility on start
decorations
boolean
true
Show window decorations
transparent
boolean
false
Enable window transparency
alwaysOnTop
boolean
false
Keep window above others
url
string
"index.html"
Initial URL to load
字段类型默认值描述
title
字符串
"Tauri"
窗口标题
width
/ 
height
数字
800
/ 
600
窗口像素尺寸
minWidth
/ 
minHeight
数字-最小尺寸
maxWidth
/ 
maxHeight
数字-最大尺寸
x
/ 
y
数字-窗口位置
resizable
布尔值
true
允许调整窗口大小
fullscreen
布尔值
false
以全屏模式启动
center
布尔值
false
在屏幕中央显示窗口
visible
布尔值
true
启动时窗口是否可见
decorations
布尔值
true
显示窗口装饰
transparent
布尔值
false
启用窗口透明效果
alwaysOnTop
布尔值
false
保持窗口在其他窗口上方
url
字符串
"index.html"
初始加载的URL

Security Configuration

安全配置

FieldTypeDescription
capabilities
string[]Permission capabilities for the application
assetProtocol.enable
booleanEnable custom asset protocol
assetProtocol.scope
string[]Allowed paths for asset protocol
pattern.use
stringSecurity pattern (
"brownfield"
default)
freezePrototype
booleanPrevent prototype mutation
字段类型描述
capabilities
字符串数组应用的权限能力
assetProtocol.enable
布尔值启用自定义资源协议
assetProtocol.scope
字符串数组资源协议允许的路径
pattern.use
字符串安全模式（默认值为 
"brownfield"
）
freezePrototype
布尔值阻止原型修改

Bundle Targets by Platform

按平台划分的打包目标

PlatformTargets
Windows
nsis
, 
msi
macOS
app
, 
dmg
Linux
appimage
, 
deb
, 
rpm
Android
apk
, 
aab
iOS
app
平台目标格式
Windows
nsis
, 
msi
macOS
app
, 
dmg
Linux
appimage
, 
deb
, 
rpm
Android
apk
, 
aab
iOS
app

Platform-Specific Configuration

平台特定配置

Create platform-specific files that override base configuration using JSON Merge Patch (RFC 7396).
PlatformFilename
Linux
tauri.linux.conf.json
Windows
tauri.windows.conf.json
macOS
tauri.macos.conf.json
Android
tauri.android.conf.json
iOS
tauri.ios.conf.json
Example 
src-tauri/tauri.windows.conf.json
:
json
{
  "app": {
    "windows": [{ "title": "My App - Windows Edition" }]
  },
  "bundle": {
    "windows": { "nsis": { "installMode": "perMachine" } }
  }
}
Example 
src-tauri/tauri.macos.conf.json
:
json
{
  "app": { "macOSPrivateApi": true },
  "bundle": {
    "macOS": { "minimumSystemVersion": "11.0", "entitlements": "entitlements.plist" }
  }
}
使用JSON合并补丁（RFC 7396）创建覆盖基础配置的平台特定文件。
平台文件名
Linux
tauri.linux.conf.json
Windows
tauri.windows.conf.json
macOS
tauri.macos.conf.json
Android
tauri.android.conf.json
iOS
tauri.ios.conf.json
示例 
src-tauri/tauri.windows.conf.json
：
json
{
  "app": {
    "windows": [{ "title": "My App - Windows Edition" }]
  },
  "bundle": {
    "windows": { "nsis": { "installMode": "perMachine" } }
  }
}
示例 
src-tauri/tauri.macos.conf.json
：
json
{
  "app": { "macOSPrivateApi": true },
  "bundle": {
    "macOS": { "minimumSystemVersion": "11.0", "entitlements": "entitlements.plist" }
  }
}

CLI Configuration Override

CLI配置覆盖

bash
undefined
bash
undefined

Development with custom config

使用自定义配置进行开发

tauri dev --config src-tauri/tauri.dev.conf.json
tauri dev --config src-tauri/tauri.dev.conf.json

Build with beta configuration

使用beta配置构建

tauri build --config src-tauri/tauri.beta.conf.json
tauri build --config src-tauri/tauri.beta.conf.json

Inline configuration override

内联配置覆盖

tauri build --config '{"bundle":{"identifier":"com.company.myapp.beta"}}'
undefined
tauri build --config '{"bundle":{"identifier":"com.company.myapp.beta"}}'
undefined

Cargo.toml Configuration

Cargo.toml 配置

Located in 
src-tauri/Cargo.toml
, manages Rust dependencies.
toml
[package]
name = "my-app"
version = "1.0.0"
edition = "2021"

[build-dependencies]
tauri-build = { version = "2.0", features = [] }

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tauri = { version = "2.0", features = [] }
tauri-plugin-shell = "2.0"
tauri-plugin-opener = "2.0"

[features]
default = ["custom-protocol"]
custom-protocol = ["tauri/custom-protocol"]
位于 
src-tauri/Cargo.toml
，用于管理Rust依赖项。
toml
[package]
name = "my-app"
version = "1.0.0"
edition = "2021"

[build-dependencies]
tauri-build = { version = "2.0", features = [] }

[dependencies]
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
tauri = { version = "2.0", features = [] }
tauri-plugin-shell = "2.0"
tauri-plugin-opener = "2.0"

[features]
default = ["custom-protocol"]
custom-protocol = ["tauri/custom-protocol"]

Common Tauri Features

常见Tauri特性

toml
[dependencies]
tauri = { version = "2.0", features = [
  "config-json5",      # Enable JSON5 config format
  "config-toml",       # Enable TOML config format
  "devtools",          # Enable WebView devtools
  "macos-private-api", # Enable macOS private APIs
  "tray-icon",         # Enable system tray support
  "image-png",         # PNG image support
  "image-ico",         # ICO image support
  "protocol-asset"     # Custom asset protocol
] }
toml
[dependencies]
tauri = { version = "2.0", features = [
  "config-json5",      # 启用JSON5配置格式
  "config-toml",       # 启用TOML配置格式
  "devtools",          # 启用WebView开发者工具
  "macos-private-api", # 启用macOS私有API
  "tray-icon",         # 启用系统托盘支持
  "image-png",         # PNG图片支持
  "image-ico",         # ICO图片支持
  "protocol-asset"     # 自定义资源协议
] }

Version Management

版本管理

toml
tauri = { version = "2.0" }       # Semver-compatible (recommended)
tauri = { version = "=2.0.0" }    # Exact version
tauri = { version = "~2.0.0" }    # Patch updates only
toml
tauri = { version = "2.0" }       # 兼容Semver版本（推荐）
tauri = { version = "=2.0.0" }    # 精确版本
tauri = { version = "~2.0.0" }    # 仅更新补丁版本

package.json Integration

package.json 集成

json
{
  "name": "my-tauri-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "tauri": "tauri"
  },
  "dependencies": { "@tauri-apps/api": "^2.0.0" },
  "devDependencies": { "@tauri-apps/cli": "^2.0.0" }
}
json
{
  "name": "my-tauri-app",
  "version": "1.0.0",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "tauri": "tauri"
  },
  "dependencies": { "@tauri-apps/api": "^2.0.0" },
  "devDependencies": { "@tauri-apps/cli": "^2.0.0" }
}

Environment-Specific Configurations

特定环境配置

Development (
src-tauri/tauri.dev.conf.json
)

开发环境（
src-tauri/tauri.dev.conf.json
）

json
{
  "build": { "devUrl": "http://localhost:5173" },
  "app": {
    "withGlobalTauri": true,
    "windows": [{ "title": "My App [DEV]" }]
  }
}
json
{
  "build": { "devUrl": "http://localhost:5173" },
  "app": {
    "withGlobalTauri": true,
    "windows": [{ "title": "My App [DEV]" }]
  }
}

Production (
src-tauri/tauri.prod.conf.json
)

生产环境（
src-tauri/tauri.prod.conf.json
）

json
{
  "build": { "frontendDist": "../dist", "removeUnusedCommands": true },
  "bundle": { "active": true, "targets": "all" }
}
json
{
  "build": { "frontendDist": "../dist", "removeUnusedCommands": true },
  "bundle": { "active": true, "targets": "all" }
}

Beta (
src-tauri/tauri.beta.conf.json
)

Beta环境（
src-tauri/tauri.beta.conf.json
）

json
{
  "identifier": "com.company.myapp.beta",
  "productName": "MyApp Beta",
  "plugins": {
    "updater": {
      "endpoints": ["https://beta-releases.example.com/{{target}}/{{arch}}/{{current_version}}"]
    }
  }
}
json
{
  "identifier": "com.company.myapp.beta",
  "productName": "MyApp Beta",
  "plugins": {
    "updater": {
      "endpoints": ["https://beta-releases.example.com/{{target}}/{{arch}}/{{current_version}}"]
    }
  }
}

TOML Configuration Format

TOML配置格式

When using 
Tauri.toml
, configuration uses kebab-case:
toml
[build]
dev-url = "http://localhost:3000"
before-dev-command = "npm run dev"
before-build-command = "npm run build"

[app]
with-global-tauri = false

[[app.windows]]
title = "My Application"
width = 1200
height = 800
resizable = true
center = true

[app.security]
freeze-prototype = false

[app.security.asset-protocol]
enable = true
scope = ["$APPDATA/**"]

[bundle]
active = true
targets = "all"
icon = ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"]

[plugins.updater]
pubkey = "YOUR_PUBLIC_KEY"
endpoints = ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"]
使用 
Tauri.toml
时，配置采用短横线命名法：
toml
[build]
dev-url = "http://localhost:3000"
before-dev-command = "npm run dev"
before-build-command = "npm run build"

[app]
with-global-tauri = false

[[app.windows]]
title = "My Application"
width = 1200
height = 800
resizable = true
center = true

[app.security]
freeze-prototype = false

[app.security.asset-protocol]
enable = true
scope = ["$APPDATA/**"]

[bundle]
active = true
targets = "all"
icon = ["icons/32x32.png", "icons/128x128.png", "icons/icon.icns", "icons/icon.ico"]

[plugins.updater]
pubkey = "YOUR_PUBLIC_KEY"
endpoints = ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"]

Common Configuration Patterns

常见配置模式

Multi-Window Application

多窗口应用

json
{
  "app": {
    "windows": [
      { "label": "main", "title": "Main Window", "width": 1200, "height": 800, "url": "index.html" },
      { "label": "settings", "title": "Settings", "width": 600, "height": 400, "url": "settings.html", "visible": false }
    ]
  }
}
json
{
  "app": {
    "windows": [
      { "label": "main", "title": "Main Window", "width": 1200, "height": 800, "url": "index.html" },
      { "label": "settings", "title": "Settings", "width": 600, "height": 400, "url": "settings.html", "visible": false }
    ]
  }
}

System Tray Application

系统托盘应用

json
{
  "app": {
    "trayIcon": { "id": "main-tray", "iconPath": "icons/tray.png", "iconAsTemplate": true },
    "windows": [{ "visible": false }]
  }
}
json
{
  "app": {
    "trayIcon": { "id": "main-tray", "iconPath": "icons/tray.png", "iconAsTemplate": true },
    "windows": [{ "visible": false }]
  }
}

Plugin Configuration

插件配置

json
{
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY",
      "endpoints": ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"],
      "windows": { "installMode": "passive" }
    },
    "shell": {
      "open": true,
      "scope": [{ "name": "open-url", "cmd": "open", "args": [{ "validator": "\\S+" }] }]
    },
    "deep-link": {
      "mobile": ["myapp"],
      "desktop": { "schemes": ["myapp"] }
    }
  }
}
json
{
  "plugins": {
    "updater": {
      "pubkey": "YOUR_PUBLIC_KEY",
      "endpoints": ["https://releases.example.com/{{target}}/{{arch}}/{{current_version}}"],
      "windows": { "installMode": "passive" }
    },
    "shell": {
      "open": true,
      "scope": [{ "name": "open-url", "cmd": "open", "args": [{ "validator": "\\S+" }] }]
    },
    "deep-link": {
      "mobile": ["myapp"],
      "desktop": { "schemes": ["myapp"] }
    }
  }
}

Lock Files

锁定文件

Commit lock files for reproducible builds:
FilePurpose
Cargo.lock
Locks Rust dependency versions
package-lock.json
Locks npm dependency versions
yarn.lock
Locks Yarn dependency versions
pnpm-lock.yaml
Locks pnpm dependency versions
提交锁定文件以实现可复现的构建：
文件用途
Cargo.lock
锁定Rust依赖项版本
package-lock.json
锁定npm依赖项版本
yarn.lock
锁定Yarn依赖项版本
pnpm-lock.yaml
锁定pnpm依赖项版本

Configuration Validation

配置验证

Use the JSON schema for editor autocompletion:
json
{ "$schema": "https://schema.tauri.app/config/2" }
Run 
tauri info
to verify configuration and environment setup.
使用JSON schema实现编辑器自动补全：
json
{ "$schema": "https://schema.tauri.app/config/2" }
运行 
tauri info
验证配置和环境设置是否正确。