fancy-installer

A configurable, theme-driven installer for Electron apps — built on Tauri. 给 Electron 应用做一个自定义 UI 的安装器，只用改一份 JSON 配置。

为什么需要它？

• electron-builder 自带的 NSIS 安装器既丑又老
• Velopack / Squirrel 风格固定，没法做品牌定制
• 自己用 Tauri / NSIS / Inno 撸一个又要啃半天

fancy-installer 解决的是：配置 + 主题切换就能拿到一个开箱即用、视觉现代的安装器。 最终产物是一个 ~10MB + payload 的单文件 exe，把 Electron 应用打包在里面，运行后释放到用户机器、写注册表、建快捷方式、最后启动。

特性

• 🎨 四套内置主题：aurora / minimal / cyberpunk / retro-mac
• 🧩 配置驱动：所有文案、主色、特性胶囊都在 installer.config.json 里改
• 🌍 跨平台：Windows ✅ · macOS ⚠️ Experimental · Linux ⚠️ Experimental
• 🔌 Electron 自动集成：从 package.json 自动读取 productName / version / publisher / appId，复用项目图标
• 📦 极致压缩：tar + zstd-19 比 zip 省 20-30%
• 🪟 真正的系统集成：Windows 注册表卸载项 + 开始菜单/桌面快捷方式；macOS LaunchServices 注册；Linux .desktop 项
• 🎭 演示模式：未打包 payload 也能 npm run tauri:dev 看 UI 效果

一行命令开始

npx create-fancy-installer my-installer

CLI 会问你 appName / 主题 / publisher，自动克隆模板 + 安装依赖 + git init。

或者手动 clone：

git clone https://github.com/<your>/fancy-installer
cd fancy-installer
npm install
npm run tauri:dev     # 演示模式，直接看 UI

端到端示例（含真实 Electron 应用）

cd examples/hello-electron && npm install && npm run build:unpack
cd ../.. && npm run pack -- --electron examples/hello-electron

成品落在 examples/hello-electron/release/HelloElectron-Setup-1.0.0.exe。

四套主题

| 主题 | 风格 | 适合 | |------|------|------| | aurora | 深色玻璃拟态、极光漂移、反应堆动效、粒子爆发 | C 端视觉向应用 | | minimal | 浅色卡片、简洁进度条、极简徽章 | 企业级 / 开发者工具 | | cyberpunk | 霓虹紫粉、扫描线、ASCII 像素、雷达扫描 | 游戏、工具向、复古赛博 | | retro-mac | Mac OS Platinum、横条标题栏、凸起按钮 | 复古、独立游戏、致敬 |

切主题就改一行：

{ "theme": "cyberpunk" }

配置

installer.config.json 一份文件管所有：

{
  "appName": "MyApp",
  "appDisplayName": "My App",
  "appPublisher": "Your Company",
  "appVersion": "1.0.0",
  "exeName": "MyApp.exe",
  "appDescription": "...",
  "appIdentifier": "com.yourcompany.myapp",

  "theme": "aurora",
  "primaryColor": "#f43f5e",
  "accentColor": "#06b6d4",
  "successColor": "#10b981",

  "texts": {
    "welcomeTitle": "欢迎安装",
    "welcomeSubtitle": "...",
    "installButton": "开始安装",
    "licenseAgreement": "《许可协议及隐私条款》",
    "progressFrames": [
      { "limit": 25, "text": "..." },
      { "limit": 100, "text": "..." }
    ],
    "successTitle": "安装成功",
    "successSubtitle": "...",
    "features": [
      { "label": "极速启动", "color": "#10b981" }
    ],
    "launchButton": "立即启动"
  }
}

打包

npm run pack                              # 默认 electron 项目 = ..
npm run pack -- --electron ../my-app      # 指定 electron 项目路径
npm run pack -- --skip-build              # 只刷新 payload + 配置

流程：

1. 从 Electron 项目 package.json 推断 identity
2. 用 Electron 项目的图标重新生成 Tauri 全套图标
3. 跨平台探测 unpacked 目录（release/win-unpacked/ · release/mac*/X.app/ · release/linux-unpacked/）
4. 用 zstd-19 把 unpacked 压成 payload.tar.zst
5. 调 tauri build 编译最终 exe
6. 把成品拷到 Electron 项目的 release/ 目录

跨平台支持

| 平台 | 状态 | 安装位置 | 集成方式 | |------|------|---------|--------| | Windows 10/11 x64 | ✅ Stable | %LOCALAPPDATA%\<AppName>\ | 注册表 Uninstall + 开始菜单 .lnk + 桌面 .lnk | | macOS (Intel / Apple Silicon) | ⚠️ Experimental | /Applications/<AppName>.app/ | lsregister 注册 LaunchServices | | Linux (Ubuntu / Fedora) | ⚠️ Experimental | ~/.local/share/<AppName>/ | .desktop entry 到 ~/.local/share/applications/ |

平台特异代码隔离在 src-tauri/src/platform/{windows,macos,linux}.rs，每个文件实现三个函数：default_install_root / install_finalize / launch_installed_app。要扩展或修复某平台只需改对应文件。

自定义主题

每个主题就是一个 React 组件：

// src/themes/my-theme/index.tsx
import type { ThemeProps } from "../../types";

export default function MyTheme({ config, state }: ThemeProps) {
  return (
    <div>
      <h1>{config.texts.welcomeTitle}</h1>
      <button onClick={state.startInstall}>{config.texts.installButton}</button>
    </div>
  );
}

在 src/themes/index.ts 注册即可。

ThemeProps 提供：

• config: NormalizedConfig — 全套配置（appName / 颜色 / 文案 / 特性胶囊）
• state: InstallerState — step / progress / installPath / selectPath() / startInstall() / launch() / close()

所有安装逻辑（路径选择、进度订阅、Tauri 通信）由 useInstaller hook 统一管理，主题只负责 UI。

工作原理

你的 Electron 项目                fancy-installer
─────────────────                ───────────────
release/win-unpacked/  ─┐
（或 mac*/X.app）        │  npm run pack
（或 linux-unpacked）   │  ───────────────────►
package.json (产品名等)  │
build/icon.png         ─┘
                                 ┌─ installer.config.json (嵌入)
                                 ├─ payload.tar.zst        (嵌入)
                                 └─ icons/                  (重新生成)
                                              │
                                              ▼
                                       tauri build
                                              │
                                              ▼
                              MyApp-Setup-1.0.0.exe / .app

最终二进制内嵌：

• installer.config.json（include_str!）
• payload.tar.zst（include_bytes!）
• Tauri runtime + WebView2 / WKWebView 包装

运行时：

1. 加载嵌入的 config → 渲染对应主题
2. "开始安装" → 解压 payload 到目标目录
3. 平台特异收尾（注册表 / LaunchServices / .desktop）
4. "立即启动" → 拉起已安装的程序

目录结构

fancy-installer/
├── installer.config.json     # 唯一需要改的配置
├── src/
│   ├── App.tsx               # 主题路由（极薄一层）
│   ├── useInstaller.ts       # 共享状态 hook
│   ├── types.ts              # 配置 + 主题协议
│   └── themes/
│       ├── aurora/
│       ├── minimal/
│       ├── cyberpunk/
│       └── retro-mac/
├── src-tauri/
│   ├── src/
│   │   ├── lib.rs            # 通用解压 + 命令分发
│   │   └── platform/         # 跨平台抽象
│   │       ├── windows.rs
│   │       ├── macos.rs
│   │       └── linux.rs
│   ├── build.rs              # 读 config，写编译期常量
│   └── payload/              # pack.js 生成
├── scripts/
│   ├── pack.js               # 一键打包：electron → 安装器
│   └── gen-icons.mjs         # SVG → 全套平台图标
├── packages/
│   └── create-fancy-installer/  # npx 脚手架 CLI
├── assets/logo.svg           # 项目主图标源
└── examples/
    └── hello-electron/       # 最小可工作 Electron 示例

演示模式

如果 src-tauri/payload/payload.tar.zst 不存在或为空，build.rs 自动创建空文件让 Rust 编译通过；运行时 run_installation 检测到空 payload 后只模拟 0→100 的进度（约 3 秒），不写任何文件。这样不需要 Electron 项目也能预览 UI。

License

MIT

致谢

• Tauri — 让 web 技术做 native installer 成为可能
• framer-motion — 流畅的入场/出场编排
• zstd — 比 zip 小 20-30% 的压缩