본문으로 건너뛰기

Tauri v2 패키징 가이드

작성일: 2026-04-06 Last Updated: 2026-04-06 대상: Tauri v2 데스크탑 앱 패키징 (Windows / macOS / Linux) 공통 참조: ../common/ci-cd.md (빌드 파이프라인, 아티팩트 관리) 관련 문서: ./code-signing.md (코드 서명), ./auto-update.md (자동 업데이트)


목차

  1. 패키징 포맷 개요
  2. Windows 패키징
  3. macOS 패키징
  4. Linux 패키징
  5. 아이콘 / 메타데이터
  6. 파일 연결 (File Association)
  7. Deep Link / Custom Protocol
  8. 설치 경로 / 데이터 경로
  9. 언인스톨러

1. 패키징 포맷 개요

포맷별 비교

포맷OS자동 업데이트설치 방식크기추천
NSISWindowsO인스톨러 (.exe)작음기본
MSI (WiX)WindowsOWindows Installer중간IT 관리자
DMGmacOSX (배포용)드래그 앤 드롭중간기본
.appmacOSO (업데이트)직접 실행작음업데이트용
AppImageLinuxO독립 실행 (설치 불필요)기본
debLinux (Debian)Xdpkg -i / apt작음Debian/Ubuntu
rpmLinux (RHEL)Xrpm -i / dnf작음Fedora/RHEL
FlatpakLinuxO (Flathub)샌드박스범용
SnapLinuxO (자동)샌드박스Ubuntu

tauri.conf.json 번들 설정

{
"bundle": {
"active": true,
"targets": "all",
"icon": [
"icons/32x32.png",
"icons/128x128.png",
"icons/128x128@2x.png",
"icons/icon.icns",
"icons/icon.ico"
],
"identifier": "com.example.myapp",
"publisher": "My Company",
"copyright": "Copyright (c) 2026 My Company",
"category": "Productivity",
"shortDescription": "A desktop application",
"longDescription": "A cross-platform desktop application built with Tauri.",
"resources": [],
"externalBin": [],
"windows": { },
"macOS": { },
"linux": { }
}
}

특정 포맷만 빌드

# 특정 타겟만 빌드
npx tauri build --bundles nsis # Windows NSIS만
npx tauri build --bundles msi # Windows MSI만
npx tauri build --bundles dmg # macOS DMG만
npx tauri build --bundles app # macOS .app만
npx tauri build --bundles appimage # Linux AppImage만
npx tauri build --bundles deb # Linux deb만
npx tauri build --bundles rpm # Linux rpm만

2. Windows 패키징

2.1 NSIS 인스톨러 (기본 추천)

NSIS(Nullsoft Scriptable Install System)는 가볍고 커스터마이징이 용이한 인스톨러이다.

// tauri.conf.json > bundle > windows > nsis
{
"bundle": {
"windows": {
"nsis": {
"displayLanguageSelector": true,
"languages": ["Korean", "English", "Japanese"],
"installerIcon": "icons/installer.ico",
"headerImage": "icons/nsis-header.bmp",
"sidebarImage": "icons/nsis-sidebar.bmp",
"installMode": "both",
"startMenuFolder": "My Company"
}
}
}
}
필드설명
displayLanguageSelector언어 선택 대화상자 표시
languages지원 언어 목록
installerIcon설치 프로그램 아이콘 (.ico)
headerImageNSIS 헤더 이미지 (150x57 BMP)
sidebarImageNSIS 사이드바 이미지 (164x314 BMP)
installModecurrentUser / perMachine / both (사용자 선택)
startMenuFolder시작 메뉴 폴더명

installMode 비교

모드설치 경로UAC 프롬프트사용 사례
currentUser%LOCALAPPDATA%\{app}불필요개인 사용자
perMachineC:\Program Files\{app}필요기업 환경, IT 관리
both사용자 선택선택에 따라기본 추천

2.2 MSI (WiX 기반)

기업 IT 환경에서 Group Policy 배포가 필요할 때 MSI를 사용한다.

// tauri.conf.json > bundle > windows > wix
{
"bundle": {
"windows": {
"wix": {
"language": ["ko-KR", "en-US"],
"bannerPath": "icons/wix-banner.bmp",
"dialogImagePath": "icons/wix-dialog.bmp"
}
}
}
}

NSIS vs MSI 비교

항목NSISMSI (WiX)
설치 UI커스텀 가능Windows 표준
Group Policy 배포XO
무음 설치--silentmsiexec /i /qn
파일 크기작음중간
자동 업데이트O (Tauri Updater)O (Tauri Updater)
권장 대상일반 사용자기업 IT 관리자

2.3 Portable (설치 불필요)

Tauri는 공식적으로 Portable 빌드를 제공하지 않지만, Rust 바이너리 자체를 배포할 수 있다.

# Release 빌드 바이너리를 직접 배포
target/release/myapp.exe

# WebView2가 시스템에 설치되어 있어야 함
# Windows 10 1803+ / Windows 11은 기본 포함

3. macOS 패키징

3.1 DMG (배포용)

DMG는 macOS에서 가장 일반적인 배포 형식이다.

// tauri.conf.json > bundle > macOS
{
"bundle": {
"macOS": {
"dmg": {
"appPosition": { "x": 180, "y": 170 },
"applicationFolderPosition": { "x": 480, "y": 170 },
"windowSize": { "width": 660, "height": 400 },
"background": "icons/dmg-background.png"
},
"minimumSystemVersion": "10.15",
"hardenedRuntime": true,
"entitlements": "./entitlements.plist",
"frameworks": []
}
}
}

DMG 레이아웃 설명

+-----------------------------------------------+
| DMG Window (660x400) |
| |
| [MyApp.app] [Applications/] |
| (180, 170) (480, 170) |
| |
| "MyApp을 Applications 폴더로 |
| 드래그하세요" |
| |
+-----------------------------------------------+

3.2 .app 번들 구조

Tauri가 생성하는 macOS .app 번들:

MyApp.app/
+-- Contents/
+-- Info.plist # 앱 메타데이터
+-- MacOS/
| +-- MyApp # 메인 바이너리
+-- Resources/
| +-- icon.icns # 앱 아이콘
| +-- *.lproj/ # 지역화 리소스
+-- Frameworks/ # 의존 프레임워크
+-- _CodeSignature/ # 코드 서명

3.3 Universal Binary (Intel + Apple Silicon)

# 두 아키텍처 모두 빌드
npx tauri build --target aarch64-apple-darwin # Apple Silicon
npx tauri build --target x86_64-apple-darwin # Intel

# Universal Binary 생성 (선택사항)
lipo -create \
target/aarch64-apple-darwin/release/myapp \
target/x86_64-apple-darwin/release/myapp \
-output target/universal/myapp

일반적으로 Universal Binary 대신 플랫폼별 개별 빌드를 배포하는 것이 권장된다 (파일 크기 절반).


4. Linux 패키징

4.1 AppImage (기본 추천)

AppImage는 설치 없이 실행 가능한 단일 파일 형식이다.

# AppImage 실행
chmod +x MyApp_2.4.0_amd64.AppImage
./MyApp_2.4.0_amd64.AppImage

# 데스크탑 통합 (선택)
# AppImage를 ~/.local/bin/ 에 복사 후 데스크탑 파일 생성
장점단점
설치 불필요파일 크기 큼 (의존성 포함)
모든 배포판에서 실행시스템 통합 (메뉴, 연결) 수동
자동 업데이트 지원 (Tauri Updater)일부 배포판에서 sandbox 제한
이전 버전 병렬 보관 가능FUSE 필요 (대부분 기본 설치)

4.2 deb 패키지 (Debian/Ubuntu)

// tauri.conf.json > bundle > linux > deb
{
"bundle": {
"linux": {
"deb": {
"depends": [
"libwebkit2gtk-4.1-0",
"libgtk-3-0"
],
"section": "utils",
"priority": "optional",
"desktopTemplate": "assets/myapp.desktop"
}
}
}
}
# deb 설치
sudo dpkg -i myapp_2.4.0_amd64.deb
sudo apt-get install -f # 의존성 자동 해결

# 또는 apt로 직접 설치
sudo apt install ./myapp_2.4.0_amd64.deb

4.3 rpm 패키지 (Fedora/RHEL)

// tauri.conf.json > bundle > linux > rpm
{
"bundle": {
"linux": {
"rpm": {
"depends": [
"webkit2gtk4.1",
"gtk3"
],
"release": "1",
"epoch": 0
}
}
}
}
# rpm 설치
sudo rpm -i myapp-2.4.0-1.x86_64.rpm
# 또는
sudo dnf install ./myapp-2.4.0-1.x86_64.rpm

4.4 Flatpak (범용)

Tauri는 Flatpak을 직접 빌드하지 않지만, 별도 manifest로 빌드할 수 있다.

# com.example.myapp.yml (Flatpak manifest)
app-id: com.example.myapp
runtime: org.gnome.Platform
runtime-version: '45'
sdk: org.gnome.Sdk
command: myapp

finish-args:
- --share=network
- --share=ipc
- --socket=wayland
- --socket=fallback-x11
- --device=dri
- --filesystem=xdg-documents:ro

modules:
- name: myapp
buildsystem: simple
build-commands:
- install -Dm755 myapp /app/bin/myapp
sources:
- type: file
path: target/release/myapp
# Flatpak 빌드 + 설치
flatpak-builder build-dir com.example.myapp.yml --install --user --force-clean

4.5 Snap

# snap/snapcraft.yaml
name: myapp
version: '2.4.0'
summary: My Desktop App
description: |
A cross-platform desktop application.
grade: stable
confinement: strict
base: core22

apps:
myapp:
command: myapp
plugs:
- network
- home
- desktop
- desktop-legacy
- wayland
- x11
- opengl

parts:
myapp:
plugin: dump
source: target/release/
source-type: local
organize:
myapp: bin/myapp

4.6 Linux 패키지 포맷 비교

포맷배포판 호환자동 업데이트샌드박스의존성 관리배포 용이성
AppImage전체O (Tauri)X자체 포함매우 쉬움
debDebian 계열XXapt쉬움
rpmRHEL 계열XXdnf/yum쉬움
Flatpak전체O (Flathub)OFlatpak 런타임중간
Snap전체 (Ubuntu 주력)O (자동)OSnap 런타임중간

추천 전략: AppImage를 기본으로, deb/rpm을 추가 제공.

4.7 빌드 의존성 (CI)

# Ubuntu 22.04에서 Tauri 빌드에 필요한 패키지
sudo apt-get update
sudo apt-get install -y \
libwebkit2gtk-4.1-dev \
libappindicator3-dev \
librsvg2-dev \
patchelf \
libssl-dev \
libgtk-3-dev

5. 아이콘 / 메타데이터

5.1 아이콘 준비

src-tauri/icons/
+-- 32x32.png # 32x32 (Linux 트레이, Windows 작은 아이콘)
+-- 128x128.png # 128x128 (Linux 앱 아이콘)
+-- 128x128@2x.png # 256x256 (HiDPI)
+-- icon.icns # macOS 아이콘 (여러 크기 포함)
+-- icon.ico # Windows 아이콘 (여러 크기 포함)
+-- icon.png # 512x512 또는 1024x1024 (원본)
+-- StoreLogo.png # 50x50 (Microsoft Store)
+-- Square30x30Logo.png # 30x30 (Windows 타일)
+-- Square44x44Logo.png # 44x44 (Windows 타일)
+-- Square71x71Logo.png # 71x71 (Windows 타일)
+-- Square89x89Logo.png # 89x89 (Windows 타일)
+-- Square107x107Logo.png # 107x107 (Windows 타일)
+-- Square142x142Logo.png # 142x142 (Windows 타일)
+-- Square150x150Logo.png # 150x150 (Windows 타일)
+-- Square284x284Logo.png # 284x284 (Windows 타일)
+-- Square310x310Logo.png # 310x310 (Windows 타일)

Tauri CLI로 아이콘 자동 생성

# 1024x1024 원본 PNG에서 모든 크기 자동 생성
npx tauri icon src-tauri/icons/icon.png

5.2 메타데이터 (tauri.conf.json)

{
"productName": "My App",
"version": "2.4.0",
"identifier": "com.example.myapp",
"bundle": {
"publisher": "My Company Inc.",
"copyright": "Copyright (c) 2026 My Company Inc.",
"category": "Productivity",
"shortDescription": "데스크탑 앱",
"longDescription": "생산성을 높이는 크로스 플랫폼 데스크탑 앱입니다.",
"licenseFile": "./LICENSE"
}
}

macOS 카테고리 값

설명
Business비즈니스
DeveloperTools개발 도구
Education교육
Entertainment엔터테인먼트
Finance금융
GraphicsDesign그래픽/디자인
Productivity생산성
SocialNetworking소셜
Utilities유틸리티

6. 파일 연결 (File Association)

tauri.conf.json 설정

{
"bundle": {
"fileAssociations": [
{
"ext": ["myf"],
"name": "MyApp File",
"mimeType": "application/x-myapp",
"role": "Editor"
},
{
"ext": ["json", "jsonl"],
"name": "JSON File",
"mimeType": "application/json",
"role": "Viewer"
}
]
}
}

파일 연결 필드

필드설명예시
ext파일 확장자 (점 없이)["myf", "myfile"]
name파일 유형 이름 (OS 표시용)"MyApp File"
mimeTypeMIME 타입"application/x-myapp"
rolemacOS 역할 (Editor / Viewer / None)"Editor"

Rust에서 파일 열기 이벤트 처리

// macOS: 파일 더블 클릭 시 앱으로 열기
use tauri::Manager;

fn setup(app: &mut tauri::App) -> Result<(), Box<dyn std::error::Error>> {
// macOS file open event
#[cfg(target_os = "macos")]
{
let app_handle = app.handle().clone();
app.on_file_drop_event(move |event| {
// 파일 드롭 이벤트 처리
});
}

// CLI 인자로 전달된 파일 경로 처리
let args: Vec<String> = std::env::args().collect();
if args.len() > 1 {
let file_path = &args[1];
// 파일 열기 로직
app.emit("file-opened", file_path)?;
}

Ok(())
}
// Frontend: 파일 열기 이벤트 수신
import { listen } from '@tauri-apps/api/event';

const unlisten = await listen<string>('file-opened', (event) => {
const filePath = event.payload;
loadFile(filePath);
});

# 설치
cargo add tauri-plugin-deep-link
npm install @tauri-apps/plugin-deep-link
// tauri.conf.json
{
"bundle": {
"deepLink": {
"schemes": ["myapp", "com.example.myapp"]
}
}
}

7.2 플러그인 등록 + 이벤트 처리

// src-tauri/src/lib.rs
use tauri_plugin_deep_link::DeepLinkExt;

pub fn run() {
tauri::Builder::default()
.plugin(tauri_plugin_deep_link::init())
.setup(|app| {
// Deep Link 이벤트 수신
#[cfg(any(windows, target_os = "linux"))]
{
use tauri_plugin_deep_link::DeepLinkExt;
app.deep_link().on_open_url(|event| {
for url in event.urls() {
println!("Deep link received: {}", url);
// 프론트엔드로 전달
}
});
}
Ok(())
})
.run(tauri::generate_context!())
.expect("error while running");
}
// Frontend: Deep Link 수신
import { onOpenUrl } from '@tauri-apps/plugin-deep-link';

const unlisten = await onOpenUrl((urls: string[]) => {
for (const url of urls) {
console.log('Deep link:', url);
handleDeepLink(url);
}
});

function handleDeepLink(url: string): void {
const parsed = new URL(url);
// myapp://auth/callback?code=xxx
if (parsed.hostname === 'auth' && parsed.pathname === '/callback') {
const code = parsed.searchParams.get('code');
handleOAuthCallback(code);
}
}

7.3 플랫폼별 등록 방식

OS등록 방식자동 처리
macOSInfo.plist > CFBundleURLTypesO (Tauri 자동)
Windows레지스트리 HKCU\Software\Classes\{scheme}O (NSIS/MSI)
Linux.desktop 파일 > MimeTypeO (deb/rpm)

7.4 OAuth 콜백 예시

1. 앱에서 브라우저 열기: https://auth.example.com/authorize?
client_id=xxx&redirect_uri=myapp://auth/callback&...

2. 사용자 인증 후 브라우저가 리다이렉트:
myapp://auth/callback?code=auth_code_here

3. OS가 myapp:// 프로토콜을 앱으로 전달

4. 앱이 auth_code를 받아서 토큰 교환

8. 설치 경로 / 데이터 경로

8.1 플랫폼별 기본 설치 경로

OSinstallMode설치 경로
Windows (currentUser)NSIS%LOCALAPPDATA%\{productName}\
Windows (perMachine)NSISC:\Program Files\{productName}\
WindowsMSIC:\Program Files\{productName}\
macOSDMG/Applications/{productName}.app
Linuxdeb/rpm/usr/bin/ (바이너리), /usr/share/ (리소스)
LinuxAppImage사용자 선택 (보통 ~/Applications/)

8.2 앱 데이터 경로 (Tauri API)

import {
appDataDir,
appConfigDir,
appLocalDataDir,
appCacheDir,
appLogDir,
} from '@tauri-apps/api/path';

const paths = {
data: await appDataDir(), // 앱 데이터
config: await appConfigDir(), // 앱 설정
local: await appLocalDataDir(),// 로컬 데이터
cache: await appCacheDir(), // 캐시
log: await appLogDir(), // 로그
};

플랫폼별 데이터 경로

경로 타입WindowsmacOSLinux
appData%APPDATA%\{identifier}~/Library/Application Support/{identifier}~/.local/share/{identifier}
appConfig%APPDATA%\{identifier}~/Library/Application Support/{identifier}~/.config/{identifier}
appLocalData%LOCALAPPDATA%\{identifier}~/Library/Application Support/{identifier}~/.local/share/{identifier}
appCache%LOCALAPPDATA%\{identifier}\cache~/Library/Caches/{identifier}~/.cache/{identifier}
appLog%LOCALAPPDATA%\{identifier}\logs~/Library/Logs/{identifier}~/.local/share/{identifier}/logs

{identifier}tauri.conf.jsonidentifier 값 (예: com.example.myapp)

8.3 데이터 경로 관리 패턴

// Rust에서 데이터 경로 접근
use tauri::Manager;

#[tauri::command]
async fn get_data_path(app: tauri::AppHandle) -> Result<String, String> {
let data_dir = app
.path()
.app_data_dir()
.map_err(|e| e.to_string())?;

// 디렉토리 없으면 생성
std::fs::create_dir_all(&data_dir)
.map_err(|e| e.to_string())?;

Ok(data_dir.to_string_lossy().to_string())
}

#[tauri::command]
async fn get_log_path(app: tauri::AppHandle) -> Result<String, String> {
let log_dir = app
.path()
.app_log_dir()
.map_err(|e| e.to_string())?;

std::fs::create_dir_all(&log_dir)
.map_err(|e| e.to_string())?;

Ok(log_dir.to_string_lossy().to_string())
}

9. 언인스톨러

9.1 플랫폼별 언인스톨 동작

OS포맷언인스톨 방법데이터 삭제
Windows (NSIS)제어판 > 프로그램 제거설치 파일만 삭제X (기본)
Windows (MSI)제어판 > 프로그램 제거설치 파일만 삭제X (기본)
macOS앱을 휴지통으로 이동.app 번들만 삭제X
Linux (deb)sudo apt remove myapp설치 파일만 삭제X
Linux (rpm)sudo dnf remove myapp설치 파일만 삭제X
Linux (AppImage)파일 삭제파일만 삭제X

중요: 모든 플랫폼에서 기본적으로 앱 데이터($APPDATA 등)는 언인스톨 시 보존된다.

9.2 데이터 보존 정책

데이터 유형언인스톨 시이유
사용자 설정보존재설치 시 복원
로그인 토큰삭제 권장보안
캐시삭제불필요
사용자 생성 파일보존사용자 데이터
로그보존 (선택)디버깅용

9.3 NSIS 커스텀 언인스톨 스크립트

NSIS에서 데이터 삭제 옵션을 제공하려면 커스텀 스크립트를 작성한다:

// tauri.conf.json > bundle > windows > nsis
{
"nsis": {
"installerScript": "scripts/nsis/installer.nsi"
}
}

9.4 macOS 데이터 정리 안내

macOS에서는 앱 삭제 후에도 데이터가 남으므로, 앱 내에서 "데이터 완전 삭제" 기능을 제공하는 것이 좋다.

#[tauri::command]
async fn clear_all_data(app: tauri::AppHandle) -> Result<(), String> {
let paths = vec![
app.path().app_data_dir(),
app.path().app_config_dir(),
app.path().app_cache_dir(),
app.path().app_log_dir(),
];

for path_result in paths {
if let Ok(path) = path_result {
if path.exists() {
std::fs::remove_dir_all(&path)
.map_err(|e| format!("Failed to remove {:?}: {}", path, e))?;
}
}
}

Ok(())
}
// Frontend: 설정 화면에서 "모든 데이터 삭제" 버튼
async function clearAllAppData(): Promise<void> {
const confirmed = await confirm(
'모든 앱 데이터를 삭제하시겠습니까?\n이 작업은 되돌릴 수 없습니다.',
{ title: '데이터 삭제', kind: 'warning' }
);

if (confirmed) {
await invoke('clear_all_data');
// 앱 종료
await exit(0);
}
}

패키징 전체 체크리스트

아이콘 / 메타데이터

  • 원본 아이콘 1024x1024 PNG 준비
  • npx tauri icon으로 모든 크기 생성
  • tauri.conf.json에 메타데이터 작성 (이름, 설명, 저작권, 카테고리)
  • identifier 역도메인 형식 설정 (com.company.app)

Windows

  • NSIS 설정 (언어, 아이콘, installMode)
  • MSI 빌드 테스트 (기업 배포 필요 시)
  • 코드 서명 연동 확인

macOS

  • DMG 레이아웃 설정 (위치, 배경)
  • entitlements.plist 작성
  • 최소 시스템 버전 설정 (10.15+)
  • Universal Binary 필요 여부 결정

Linux

  • AppImage 빌드 + 실행 테스트
  • deb 패키지 빌드 + 의존성 확인
  • rpm 패키지 빌드 (필요 시)
  • 빌드 의존성 패키지 목록 정리
  • 파일 연결 설정 (필요 시)
  • Custom Protocol 등록 (필요 시)
  • Deep Link 수신 테스트 (각 OS)

데이터 관리

  • 데이터/설정/캐시/로그 경로 정리
  • 언인스톨 시 데이터 보존 정책 결정
  • "데이터 완전 삭제" 기능 구현 (선택)