Tauri配置详解：tauri.conf.json的每一个选项-优快云博客

Tauri配置详解：tauri.conf.json的每一个选项

【免费下载链接】tauri Build smaller, faster, and more secure desktop applications with a web frontend. 项目地址: https://gitcode.com/GitHub_Trending/ta/tauri

1. 配置文件概述

tauri.conf.json是Tauri应用的核心配置文件，它定义了应用的构建规则、窗口行为、权限控制等关键特性。该文件采用JSON格式，通常位于项目根目录或src-tauri目录下。通过合理配置此文件，开发者可以精确控制Tauri应用的打包、运行和安全策略。

2. 顶层配置结构

Tauri配置文件包含四个顶层节点，每个节点负责不同方面的配置：

{
  "package": {},    // 应用元数据配置
  "build": {},      // 构建流程配置
  "tauri": {},      // Tauri核心功能配置
  "$schema": ""     // JSON Schema路径（可选）
}

2.1 package节点

用于定义应用的基本元数据，影响安装包信息和应用标识：

选项	类型	描述	示例
productName	string	应用名称，显示在安装界面和系统中	"Tauri API"
version	string	应用版本号，遵循语义化版本规范	"1.0.0"

"package": {
  "productName": "Tauri API",
  "version": "1.0.0"
}

2.2 build节点

控制前端资源的构建和集成流程：

选项	类型	描述	示例
distDir	string	前端构建产物目录路径	"../dist"
devPath	string	开发环境服务地址或本地路径	"http://localhost:5173"
beforeDevCommand	string	开发模式启动前执行的命令	"pnpm dev"
beforeBuildCommand	string	构建前执行的命令	"pnpm build"

"build": {
  "distDir": "../dist",
  "devPath": "http://localhost:5173",
  "beforeDevCommand": "pnpm dev",
  "beforeBuildCommand": "pnpm build"
}

3. tauri节点详解

tauri节点是配置的核心，包含应用运行时的所有关键设置：

3.1 应用基础配置

选项	类型	描述	示例
pattern	object	隔离模式配置	`{"use": "isolation", "options": {"dir": "../isolation-dist/"}}`
macOSPrivateApi	boolean	是否启用macOS私有API	true
cli	object	命令行参数定义	详见3.2节

"tauri": {
  "pattern": {
    "use": "isolation",
    "options": {
      "dir": "../isolation-dist/"
    }
  },
  "macOSPrivateApi": true
}

3.2 CLI配置

定义应用支持的命令行参数和子命令：

"cli": {
  "description": "Tauri API example",
  "args": [
    {
      "short": "c",
      "name": "config",
      "takesValue": true,
      "description": "Config path"
    },
    {
      "short": "t",
      "name": "theme",
      "takesValue": true,
      "description": "App theme",
      "possibleValues": ["light", "dark", "system"]
    },
    {
      "short": "v",
      "name": "verbose",
      "multipleOccurrences": true,
      "description": "Verbosity level"
    }
  ],
  "subcommands": {
    "update": {
      "description": "Updates the app",
      "args": [
        {
          "short": "b",
          "name": "background",
          "description": "Update in background"
        }
      ]
    }
  }
}

参数配置项说明：

选项	类型	描述
short	string	短参数名（单个字符）
name	string	长参数名
takesValue	boolean	是否需要接收值
description	string	参数描述
possibleValues	array	允许的取值列表
multipleOccurrences	boolean	是否允许多次出现

3.3 打包配置（bundle）

控制应用安装包的生成规则，支持多平台定制：

"bundle": {
  "active": true,
  "identifier": "com.tauri.api",
  "icon": [
    "../../.icons/32x32.png",
    "../../.icons/128x128.png",
    "../../.icons/128x128@2x.png",
    "../../.icons/icon.icns",
    "../../.icons/icon.ico"
  ],
  "windows": {
    "wix": {
      "language": {
        "en-US": {},
        "pt-BR": {
          "localePath": "locales/pt-BR.wxl"
        }
      }
    }
  },
  "category": "DeveloperTool",
  "copyright": "Copyright (c) 2023 Tauri",
  "shortDescription": "Tauri API演示应用",
  "longDescription": "展示Tauri框架各种API功能的示例应用"
}

关键配置项说明：

选项	类型	描述
active	boolean	是否启用打包功能
identifier	string	应用唯一标识（反向域名格式）
icon	array	应用图标路径列表（不同尺寸/格式）
category	string	应用类别（影响系统归类）
copyright	string	版权信息
windows	object	Windows平台特定配置
macOS	object	macOS平台特定配置
linux	object	Linux平台特定配置

3.4 更新器配置（updater）

配置应用自动更新功能：

"updater": {
  "active": true,
  "dialog": false,
  "pubkey": "dW50cnVzdGVkIGNvbW1lbnQ6IG1pbmlzaWduIHB1YmxpYyBrZXk6IDE5QzMxNjYwNTM5OEUwNTgKUldSWTRKaFRZQmJER1h4d1ZMYVA3dnluSjdpN2RmMldJR09hUFFlZDY0SlFqckkvRUJhZDJVZXAK",
  "endpoints": [
    "https://tauri-update-server.vercel.app/update/{{target}}/{{current_version}}"
  ]
}

配置项说明：

选项	类型	描述
active	boolean	是否启用更新功能
dialog	boolean	是否显示更新对话框
pubkey	string	用于验证更新包的公钥
endpoints	array	更新检查地址列表
interval	string	自动检查更新间隔（如"1h"）

3.5 权限控制（allowlist）

精细控制WebView可访问的Tauri API：

"allowlist": {
  "all": true,
  "fs": {
    "scope": {
      "allow": ["$APPDATA/db/**", "$DOWNLOAD/**", "$RESOURCE/**"],
      "deny": ["$APPDATA/db/*.stronghold"]
    }
  },
  "shell": {
    "open": true,
    "scope": [
      {
        "name": "sh",
        "cmd": "sh",
        "args": ["-c", { "validator": "\\S+" }]
      },
      {
        "name": "cmd",
        "cmd": "cmd",
        "args": ["/C", { "validator": "\\S+" }]
      }
    ]
  },
  "protocol": {
    "asset": true,
    "assetScope": {
      "allow": ["$APPDATA/db/**", "$RESOURCE/**"],
      "deny": ["$APPDATA/db/*.stronghold"]
    }
  },
  "http": {
    "scope": ["http://localhost:3003"]
  }
}

核心权限配置说明：

模块	配置项	描述
fs	scope	文件系统访问范围控制
shell	open	是否允许打开外部程序
shell	scope	允许执行的命令白名单
protocol	asset	是否允许访问asset协议
http	scope	允许访问的HTTP地址白名单

3.6 窗口配置（windows）

定义应用窗口的初始状态和行为：

"windows": [
  {
    "title": "Tauri应用",
    "width": 800,
    "height": 600,
    "resizable": true,
    "fullscreen": false,
    "decorations": true,
    "transparent": false,
    "center": true,
    "x": 100,
    "y": 100,
    "minWidth": 600,
    "minHeight": 400,
    "maxWidth": 1200,
    "maxHeight": 900,
    "titleBarStyle": "default"
  }
]

窗口配置项说明：

选项	类型	描述
title	string	窗口标题
width/height	number	初始宽高
resizable	boolean	是否可调整大小
fullscreen	boolean	是否全屏显示
decorations	boolean	是否显示窗口边框和标题栏
transparent	boolean	是否透明背景
center	boolean	是否居中显示
x/y	number	窗口位置坐标
minWidth/minHeight	number	最小宽高限制
titleBarStyle	string	标题栏样式（default/hidden/hiddenInset）

3.7 安全配置（security）

控制WebView安全策略和防护措施：

"security": {
  "csp": {
    "default-src": "'self' customprotocol: asset:",
    "font-src": ["https://fonts.gstatic.com"],
    "img-src": "'self' asset: https://asset.localhost blob: data:",
    "style-src": "'unsafe-inline' 'self' https://fonts.googleapis.com"
  },
  "freezePrototype": true
}

安全配置项说明：

选项	类型	描述
csp	object	内容安全策略（Content Security Policy）
freezePrototype	boolean	是否冻结JavaScript原型（防止原型污染攻击）

CSP策略详解：

指令	描述
default-src	默认资源加载策略
font-src	字体资源来源
img-src	图片资源来源
style-src	样式表来源
script-src	JavaScript来源
connect-src	网络请求来源

3.8 系统托盘配置（systemTray）

配置应用在系统托盘中的行为和外观：

"systemTray": {
  "iconPath": "../../.icons/tray_icon_with_transparency.png",
  "iconAsTemplate": true,
  "menuOnLeftClick": false
}

系统托盘配置项：

选项	类型	描述
iconPath	string	托盘图标路径
iconAsTemplate	boolean	是否将图标作为模板（macOS）
menuOnLeftClick	boolean	左键点击是否显示菜单
menu	array	托盘菜单结构定义

4. 完整配置示例

以下是一个包含主要配置项的完整示例：

{
  "package": {
    "productName": "Tauri应用示例",
    "version": "1.0.0"
  },
  "build": {
    "distDir": "../dist",
    "devPath": "http://localhost:5173",
    "beforeDevCommand": "npm run dev",
    "beforeBuildCommand": "npm run build"
  },
  "tauri": {
    "bundle": {
      "active": true,
      "identifier": "com.example.tauri-app",
      "icon": [
        "icons/32x32.png",
        "icons/128x128.png",
        "icons/icon.icns",
        "icons/icon.ico"
      ],
      "category": "Utility",
      "copyright": "Copyright (c) 2023 Example Corp"
    },
    "updater": {
      "active": true,
      "pubkey": "你的公钥",
      "endpoints": ["https://update.example.com/update/{{target}}/{{current_version}}"]
    },
    "allowlist": {
      "all": false,
      "fs": {
        "readFile": true,
        "writeFile": true,
        "scope": {
          "allow": ["$APPDATA/**"]
        }
      },
      "dialog": {
        "open": true,
        "save": true
      }
    },
    "windows": [
      {
        "title": "Tauri应用示例",
        "width": 800,
        "height": 600,
        "resizable": true,
        "center": true
      }
    ],
    "security": {
      "csp": {
        "default-src": "'self'",
        "img-src": "'self' data: asset:",
        "script-src": "'self'"
      }
    }
  }
}

5. 配置最佳实践

5.1 安全性建议

最小权限原则：禁用allowlist.all，只开放必要的API权限
严格的CSP策略：限制资源加载来源，避免使用'unsafe-inline'和'unsafe-eval'
启用原型冻结：设置security.freezePrototype: true防止原型污染
文件系统访问控制：使用fs.scope精确限制文件访问范围

5.2 性能优化

图标优化：提供多种尺寸图标，确保不同设备显示清晰
资源路径规划：合理组织distDir和资源文件位置
窗口配置：根据内容设置合适的初始窗口大小和限制

5.3 跨平台注意事项

图标格式：Windows使用ICO格式，macOS使用ICNS格式
权限差异：不同平台对系统API权限要求不同
打包配置：针对不同平台调整bundle配置中的平台特定选项

6. 常见问题解决

6.1 配置不生效

检查JSON格式是否正确（可使用JSON验证工具）
确认配置文件路径是否正确
开发模式下可能需要重启开发服务器

6.2 权限相关错误

检查allowlist配置是否正确启用了所需API
验证文件系统访问路径是否在fs.scope允许范围内
CSP策略是否阻止了必要资源加载

6.3 打包失败

检查bundle.identifier是否符合反向域名规范
确认图标文件是否存在且格式正确
检查构建命令是否能成功生成distDir目录

通过合理配置tauri.conf.json，可以充分发挥Tauri框架的优势，构建出功能完善、安全高效的桌面应用。建议根据具体项目需求逐步调整配置，并参考官方文档和示例项目获取更多配置灵感。

【免费下载链接】tauri Build smaller, faster, and more secure desktop applications with a web frontend. 项目地址: https://gitcode.com/GitHub_Trending/ta/tauri

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考