Platform-Specific Differences and Behaviors in Clash Verge Rev: Windows, macOS, and Linux Explained

Clash Verge Rev uses a unified Tauri 2 codebase with platform-specific bundle configurations that generate NSIS installers for Windows, DMG bundles for macOS, and DEB/RPM packages for Linux, each with distinct runtime behaviors for data directories and system integration.

Clash Verge Rev is a modern proxy client built with Tauri 2 that delivers a consistent React-based UI across all desktop platforms while adapting its packaging, dependencies, and runtime behavior to each operating system's requirements. Understanding these platform-specific differences is essential for developers contributing to the clash-verge-rev/clash-verge-rev repository or users troubleshooting installation issues across Windows, macOS, and Linux.

Core Architecture Across All Platforms

The application maintains a single codebase where platform divergence occurs primarily at the packaging layer. The architecture consists of four consistent layers:

• Frontend: React/Vite UI components in src/**/*.tsx (e.g., src/pages/home.tsx) run inside the Tauri webview on every OS
• Backend: Rust core plus bundled mihomo (Clash-Meta) binaries declared as sidecar binaries in the Tauri externalBin configuration
• Packaging: Tauri CLI reads platform-specific configuration files (tauri.*.conf.json) to generate the appropriate installer type for each target
• Cross-platform API: @tauri-apps/api abstracts OS-specific calls for window handling, system tray, and file system operations

Windows-Specific Behaviors

NSIS Installer Configuration

Windows builds use NSIS (Nullsoft Scriptable Install System) to generate per-machine installers. The configuration in src-tauri/tauri.windows.conf.json specifies silent WebView2 embedding and language selection:

{
  "bundle": {
    "targets": ["nsis"],
    "windows": {
      "webviewInstallMode": {
        "type": "embedBootstrapper",
        "silent": true
      },
      "nsis": {
        "displayLanguageSelector": true,
        "installerIcon": "icons/icon.ico",
        "languages": ["SimpChinese","English"],
        "installMode": "perMachine",
        "template": "./packages/windows/installer.nsi"
      }
    }
  }
}

The embedBootstrapper setting ensures that Windows installations include the WebView2 runtime even on clean systems, eliminating the need for users to manually install browser components.

Portable Mode Implementation

Clash Verge Rev supports a portable (green) version exclusively on Windows through scripts/portable.mjs. This script explicitly guards against other platforms with a process.platform !== "win32" check:

// scripts/portable.mjs (excerpt)
if (process.platform !== "win32") return;   // Windows-only guard
await fsp.mkdir(configDir, { recursive: true });
// ... bundles executable and sidecars into zip
zip.addLocalFile(path.join(releaseDir, "clash-verge.exe"));
zip.addLocalFile(path.join(releaseDir, "verge-mihomo.exe"));

The portable script creates a .config/PORTABLE marker file that the application checks at runtime to determine whether to store configuration next to the executable instead of in %APPDATA%\Clash Verge Rev.

macOS-Specific Behaviors

DMG and App Bundle Configuration

macOS distributions use app bundles packaged within DMG disk images. The src-tauri/tauri.macos.conf.json file controls the visual layout of the DMG window and code-signing requirements:

{
  "bundle": {
    "targets": ["app", "dmg"],
    "macOS": {
      "minimumSystemVersion": "10.15",
      "signingIdentity": null,
      "entitlements": "packages/macos/entitlements.plist",
      "dmg": {
        "background": "images/background.png",
        "appPosition": { "x": 180, "y": 170 },
        "applicationFolderPosition": { "x": 480, "y": 170 },
        "windowSize": { "height": 400, "width": 660 }
      },
      "infoPlist": "packages/macos/info_merge.plist"
    }
  }
}

Key macOS distinctions include:

• Minimum system version locked to macOS 10.15 (Catalina)
• Entitlements supplied via packages/macos/entitlements.plist for notarization support (developers can inject their own signing certificates)
• DMG layout customization specifying background images and icon positions for the installer window

Linux-Specific Behaviors

DEB and RPM Package Management

Linux builds generate both DEB (Debian/Ubuntu) and RPM (Fedora/RHEL) packages through src-tauri/tauri.linux.conf.json. The configuration handles platform-specific dependencies and system service integration:

{
  "bundle": {
    "targets": ["deb", "rpm"],
    "linux": {
      "deb": {
        "depends": ["openssl", "libayatana-appindicator3-1"],
        "desktopTemplate": "./packages/linux/clash-verge.desktop",
        "postInstallScript": "./packages/linux/post-install.sh",
        "preRemoveScript": "./packages/linux/pre-remove.sh"
      },
      "rpm": {
        "depends": ["openssl", "libayatana-appindicator-gtk3"],
        "desktopTemplate": "./packages/linux/clash-verge.desktop",
        "postInstallScript": "./packages/linux/post-install.sh",
        "preRemoveScript": "./packages/linux/pre-remove.sh"
      }
    },
    "externalBin": [
      "./sidecar/clash-verge-service",
      "./sidecar/verge-mihomo",
      "./sidecar/verge-mihomo-alpha"
    ]
  }
}

Notable Linux-specific behaviors include:

• Different dependency names for system tray support: libayatana-appindicator3-1 for DEB versus libayatana-appindicator-gtk3 for RPM
• Desktop entry template at packages/linux/clash-verge.desktop for application menu integration
• Service management through post-install scripts that install clash-verge-service to system paths for auto-start and TUN mode capabilities

Runtime Data Directory Behaviors

Each platform determines where Clash Verge Rev stores its configuration and data files using distinct resolution strategies:

• Windows: Checks for the presence of a PORTABLE file in the executable directory. If detected, uses a local .config folder; otherwise defaults to %APPDATA%\Clash Verge Rev
• macOS: Uses the standard Tauri path at $HOME/Library/Application Support/io.github.clash-verge-rev.clash-verge-rev
• Linux: Stores configuration in $HOME/.config/io.github.clash-verge-rev.clash-verge-rev following XDG Base Directory specifications

Building for Specific Platforms

Generate platform-specific bundles using Tauri's cross-compilation toolchain:

# Install dependencies and prepare sidecar binaries

pnpm i
pnpm run prebuild

# Windows (NSIS installer)

pnpm tauri build --target x86_64-pc-windows-msvc

# macOS (DMG for Apple Silicon)

pnpm tauri build --target aarch64-apple-darwin

# Linux (DEB package)

pnpm tauri build --target x86_64-unknown-linux-gnu

Creating Windows Portable Archives

On Windows machines, generate the portable zip distribution:

node scripts/portable.mjs

# Output: Clash.Verge_<version>_x64_portable.zip

Detecting Portable Mode at Runtime

Use the Tauri API to check for portable installations:

import { app } from '@tauri-apps/api';

const isPortable = await app.path
  .resolveResource('..\\.config\\PORTABLE')
  .then(() => true)
  .catch(() => false);

Summary

• Clash Verge Rev leverages Tauri 2 to maintain a single React/Rust codebase across Windows, macOS, and Linux
• Windows uses NSIS installers with embedded WebView2 bootstrappers and supports a unique portable mode via scripts/portable.mjs
• macOS distributes as signed DMG bundles requiring macOS 10.15+ with customizable installer layouts
• Linux provides native DEB and RPM packages with platform-specific dependencies (libayatana-appindicator3-1 vs libayatana-appindicator-gtk3) and system service integration
• Data directories vary by OS: Windows uses %APPDATA% or portable paths, macOS uses Library/Application Support, and Linux uses .config

Frequently Asked Questions

How does Clash Verge Rev handle WebView2 on Windows?

Clash Verge Rev embeds a WebView2 bootstrapper in the NSIS installer configuration (src-tauri/tauri.windows.conf.json) with "type": "embedBootstrapper" and "silent": true, ensuring the browser runtime installs automatically on clean Windows systems without requiring manual user intervention.

Can I run the portable version on macOS or Linux?

No. The portable mode is Windows-exclusive. The scripts/portable.mjs script explicitly guards against other platforms using if (process.platform !== "win32") return;, and the portable data directory logic only checks for the PORTABLE marker on Windows systems.

What are the minimum system requirements for each platform?

According to the Tauri configuration files, Windows requires x64/x86 architecture with WebView2 support, macOS requires version 10.15 (Catalina) or later (minimumSystemVersion: "10.15"), and Linux requires x64 or arm64 architecture with OpenSSL and libayatana-appindicator libraries installed.

Why does the Linux version require different dependencies for DEB and RPM packages?

The system tray library uses different package naming conventions across distributions: Debian-based systems require libayatana-appindicator3-1 while Red Hat-based systems require libayatana-appindicator-gtk3. The tauri.linux.conf.json file specifies these separately to ensure proper system tray integration on each distribution family.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}