Tauri v1 与 v2 配置对比

本文档对比 Tauri v1 和 v2 版本的配置结构和内容差异，帮助开发者了解版本变更并进行迁移。

配置结构变化

v1 配置结构

{"package": { ... },"tauri": { "allowlist": { ... },"bundle": { ... },"security": { ... },"updater": { ... },"windows": [ ... ]},"build": { ... },"plugins": { ... }
}

v2 配置结构

{"identifier": "...","productName": "...", "version": "...","app": {"security": { ... },"windows": [ ... ]},"build": { ... },"bundle": { ... }, "plugins": { ... }
}

主要变化

根级配置

v1	v2	说明
`package.productName`	`productName`	移至根级
`package.version`	`version`	移至根级
-	`identifier`	新增，必填项，应用唯一标识符
-	`mainBinaryName`	新增，可选，主二进制文件名

根级配置示例

v1 配置:

{"package": {"productName": "我的Tauri应用","version": "0.1.0"},"tauri": { ... }
}

v2 配置:

{"identifier": "com.example.myapp","productName": "我的Tauri应用","version": "0.1.0","app": { ... }
}

核心配置项

v1	v2	说明
`tauri`	`app`	重命名
`tauri.allowlist`	`app.security.capabilities`	权限系统重构
`tauri.bundle`	`bundle`	移至根级
`tauri.security`	`app.security`	移动位置
`tauri.updater`	`bundle.createUpdaterArtifacts`	简化为布尔值
`tauri.windows`	`app.windows`	移动位置

开发构建配置

v1	v2	说明
`build.devPath`	`build.devUrl`	重命名
`build.distDir`	`build.frontendDist`	重命名
`build.withGlobalTauri`	`app.withGlobalTauri`	移至app配置
-	`build.removeUnusedCommands`	新增

构建配置示例

v1 配置:

{"build": {"devPath": "http://localhost:3000","distDir": "../dist","withGlobalTauri": true}
}

v2 配置:

{"build": {"devUrl": "http://localhost:3000","frontendDist": "../dist","removeUnusedCommands": true},"app": {"withGlobalTauri": true}
}

安全配置

v1	v2	说明
`tauri.security.csp`	`app.security.csp`	位置变更
`tauri.security.freezePrototype`	`app.security.freezePrototype`	位置变更
`tauri.security.dangerousDisableAssetCspModification`	`app.security.dangerousDisableAssetCspModification`	位置变更
`tauri.security.dangerousRemoteDomainIpcAccess`	-	已移除
`tauri.security.dangerousUseHttpScheme`	-	已移除
-	`app.security.pattern`	新增安全模式配置
-	`app.security.assetProtocol`	新增资源协议安全配置

安全配置示例

v1 配置:

{"tauri": {"security": {"csp": "default-src 'self'","freezePrototype": true,"dangerousDisableAssetCspModification": false}}
}

v2 配置:

{"app": {"security": {"csp": "default-src 'self'","freezePrototype": true,"dangerousDisableAssetCspModification": false,"pattern": {"use": "brownfield"},"assetProtocol": {"enable": true,"scope": ["**/*.html", "**/*.js", "**/*.css", "**/*.png"]}}}
}

权限系统（Capabilities）

v2 引入了全新的权限系统，替代了 v1 的 allowlist。新系统更灵活、更安全，使用 capabilities 配置。

v1 权限配置 (allowlist):

{"tauri": {"allowlist": {"fs": {"all": true,"readFile": true,"writeFile": true,"scope": ["$APPDATA/**", "$APPCONFIG/**"]},"dialog": {"all": true},"shell": {"execute": true,"scope": [{ "name": "node", "cmd": "node", "args": true }]}}}
}

v2 权限配置 (capabilities):

{"app": {"security": {"capabilities": [{"identifier": "fs:default","allow": [{ "path": "$APPDATA/**" },{ "path": "$APPCONFIG/**" }]},{"identifier": "dialog:default"},{"identifier": "shell:allow-execute","permissions": ["allow-execute-command"],"commands": [{ "name": "node", "args": true }]}]}}
}

打包配置

v1	v2	说明
`tauri.bundle.active`	`bundle.active`	位置变更
`tauri.bundle.targets`	`bundle.targets`	位置变更
`tauri.bundle.icon`	`bundle.icon`	位置变更
-	`bundle.createUpdaterArtifacts`	新增，替代v1的updater配置
-	`bundle.useLocalToolsDir`	新增

平台特定配置

v1	v2	说明
`tauri.bundle.windows`	`bundle.windows`	位置变更
`tauri.bundle.macOS`	`bundle.macOS`	位置变更
`tauri.bundle.linux`	`bundle.linux`	位置变更
-	`bundle.android`	新增，支持Android平台
-	`bundle.iOS`	新增，支持iOS平台

移动平台配置

v2新增了对移动平台的支持，下面是移动平台特有的配置示例：

Android 配置:

{"bundle": {"android": {"versionCode": 1,"minSdkVersion": 24,"targetSdkVersion": 33,"icon": "icons/android-icon.png","packageName": "com.example.myapp","useCustomStatusBarColor": true,"statusBarColor": "#FFFFFF","keystore": {"path": "keystore.jks","keyAlias": "key0","password": "${ENV_PASSWORD}"}}}
}

iOS 配置:

{"bundle": {"iOS": {"developmentTeam": "ABCDE12345","minimumOsVersion": "13.0","deviceFamily": ["iphone", "ipad"],"infoPlist": {"NSCameraUsageDescription": "此应用需要访问您的相机","NSPhotoLibraryUsageDescription": "此应用需要访问您的照片库","CFBundleURLTypes": [{"CFBundleURLName": "com.example.myapp","CFBundleURLSchemes": ["myapp"]}]}}}
}

窗口配置

v1和v2的窗口配置选项基本相同，但在v2中有以下新增属性：

新增属性	说明
`shadow`	窗口是否有阴影
`theme`	窗口主题（light/dark）
`incognito`	是否使用隐身模式
`fileDropEnabled`	是否允许文件拖放
`label`	窗口标签，用于API引用

窗口配置示例

v1 配置:

{"tauri": {"windows": [{"title": "我的应用","width": 800,"height": 600,"resizable": true,"fullscreen": false}]}
}

v2 配置:

{"app": {"windows": [{"title": "我的应用","width": 800,"height": 600,"resizable": true,"fullscreen": false,"shadow": true,"theme": "light","incognito": false,"fileDropEnabled": true,"label": "main"}]}
}

插件系统变更

Tauri v2 的插件系统相比 v1 有重大更新，支持更灵活的插件配置：

v1 插件配置:

{"plugins": {"fs": {"scope": ["$APPDATA/**"]},"sql": {}}
}

v2 插件配置:

{"plugins": {"local-fs": {"scope": ["$APPDATA/**"]},"sql": {"allowedPaths": ["$APPDATA/database.sqlite"]}}
}

文件格式与平台特定配置

文件格式

两个版本都支持：

JSON: tauri.conf.json（默认）
JSON5: tauri.conf.json或tauri.conf.json5
TOML: Tauri.toml

平台特定配置

v1	v2	说明
`tauri.linux.conf.json`	`tauri.linux.conf.json`	无变化
`tauri.windows.conf.json`	`tauri.windows.conf.json`	无变化
`tauri.macos.conf.json`	`tauri.macos.conf.json`	无变化
-	`tauri.android.conf.json`	新增，Android平台配置
-	`tauri.ios.conf.json`	新增，iOS平台配置

迁移指南

从 Tauri v1 迁移到 v2 时，建议按照以下步骤操作：

必填字段添加：
- 添加必需的identifier字段，使用反向域名表示法（如com.company.app）
基本结构调整：
- 将package配置移至根级
- 将tauri更改为app
- 将bundle移至根级
构建配置更新：
- 将devPath更新为devUrl
- 将distDir更新为frontendDist
- 将withGlobalTauri移至app配置
权限系统迁移：
- 将allowlist迁移到新的capabilities权限系统
- 对每个权限定义identifier和具体的权限范围
安全配置更新：
- 将所有安全相关配置移至app.security
- 添加新的pattern和assetProtocol配置
窗口配置更新：
- 调整窗口配置路径为app.windows
- 考虑使用新增的窗口属性增强功能
更新器配置：
- 将复杂的updater配置替换为简单的bundle.createUpdaterArtifacts布尔值
移动平台支持（如需）：
- 添加bundle.android和bundle.iOS配置

迁移示例

以下是一个完整的迁移示例，展示从 v1 到 v2 的具体配置变化：

v1 配置文件:

{"package": {"productName": "我的Tauri应用","version": "0.1.0"},"tauri": {"allowlist": {"fs": {"all": true,"scope": ["$APPDATA/**"]},"dialog": {"all": true}},"bundle": {"active": true,"icon": "icons/icon.png","targets": ["deb", "msi", "dmg"]},"security": {"csp": "default-src 'self'"},"updater": {"active": true,"endpoints": ["https://example.com/update-feed.json"]},"windows": [{"title": "我的应用","width": 800,"height": 600}]},"build": {"devPath": "http://localhost:3000","distDir": "../dist"}
}

v2 配置文件:

{"identifier": "com.example.myapp","productName": "我的Tauri应用","version": "0.1.0","app": {"security": {"csp": "default-src 'self'","capabilities": [{"identifier": "fs:default","allow": [{ "path": "$APPDATA/**" }]},{"identifier": "dialog:default"}]},"windows": [{"title": "我的应用","width": 800,"height": 600,"label": "main"}]},"build": {"devUrl": "http://localhost:3000","frontendDist": "../dist"},"bundle": {"active": true,"icon": "icons/icon.png","targets": ["deb", "msi", "dmg"],"createUpdaterArtifacts": true}
}