在開發跨平台桌面應用時，開機自啓動是一個常見且重要的功能需求。本文將詳細介紹如何使用 Kotlin Multiplatform (KMP) 實現 Windows、macOS 和 Linux 三大平台的開機自啓動功能，包括接口設計、平台特性和具體實現。

所有源代碼基於我開源項目 crosspaste-desktop，如果對你有幫助歡迎點個 star ❤️

1.設計

1.1 統一接口

為了實現跨平台的開機自啓動功能，首先定義統一的接口：

AppStartUpService.kt

interface AppStartUpService {
    fun followConfig()               // 根據配置設置是否開機啓動
    fun isAutoStartUp(): Boolean     // 檢查是否已啓用開機啓動
    fun makeAutoStartUp()            // 啓用開機啓動
    fun removeAutoStartUp()          // 禁用開機啓動
}

1.2 平台分發

創建工廠類動態選擇對應平台的實現：

DesktopAppStartUpService.kt

class DesktopAppStartUpService(
    appLaunchState: DesktopAppLaunchState,
    configManager: ConfigManager,
) : AppStartUpService {
    private val currentPlatform = getPlatform()
    private val isProduction = getAppEnvUtils().isProduction()
    
    private val appStartUpService: AppStartUpService =
        when {
            currentPlatform.isMacos() -> MacAppStartUpService(configManager)
            currentPlatform.isWindows() -> WindowsAppStartUpService(appLaunchState, configManager)
            currentPlatform.isLinux() -> LinuxAppStartUpService(configManager)
            else -> throw IllegalStateException("Unsupported platform")
        }
        
    override fun followConfig() {
        if (isProduction) {
            appStartUpService.followConfig()
        }
    }
    
    // 其他方法實現...
}

2. macOS 實現

2.1 實現原理

macOS 使用 LaunchAgents 機制實現用户級自啓動，這是 Apple 官方推薦的方案：

• 配置文件位置：~/Library/LaunchAgents/
• 作用域：僅對當前用户生效
• 加載時機：用户登錄後自動加載

2.2 具體實現

MacAppStartUpService

class MacAppStartUpService(private val configManager: ConfigManager) : AppStartUpService {
   // 使用 KotlinLogging 創建日誌記錄器
   private val logger: KLogger = KotlinLogging.logger {}
   
   // 從系統屬性中獲取應用的 Bundle ID,用作 plist 文件的唯一標識符
   private val crosspasteBundleID = getSystemProperty().get("mac.bundleID")
   // 生成 plist 文件名
   private val plist = "$crosspasteBundleID.plist"
   
   override fun makeAutoStartUp() {
       try {
           // 檢查是否已經配置了自啓動
           if (!isAutoStartUp()) {
               logger.info { "Make auto startup" }
               
               // 構建 plist 文件路徑: ~/Library/LaunchAgents/xxx.plist
               // macOS 用户級自啓動配置文件必須放在該目錄下
               val plistPath = pathProvider.userHome.resolve("Library/LaunchAgents/$plist")
               
               // 創建並寫入 plist 配置文件
               filePersist.createOneFilePersist(plistPath)
                   .saveBytes("""
                       <?xml version="1.0" encoding="UTF-8"?>
                       <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN">
                       <plist version="1.0">
                       <dict>
                           <!-- Label: 唯一標識符,用於系統識別該啓動項 -->
                           <key>Label</key>
                           <string>$crosspasteBundleID</string>
                           
                           <!-- ProgramArguments: 指定要啓動的程序和參數 -->
                           <key>ProgramArguments</key>
                           <array>
                               <!-- 程序路徑: 應用程序包內的可執行文件路徑 -->
                               <string>${pathProvider.pasteAppPath.resolve("Contents/MacOS/CrossPaste")}</string>
                               <!-- --minimize 參數表示啓動時最小化窗口 -->
                               <string>--minimize</string>
                           </array>
                           
                           <!-- RunAtLoad: true 表示在用户登錄時自動啓動 -->
                           <key>RunAtLoad</key>
                           <true/>
                       </dict>
                       </plist>
                   """.trimIndent().toByteArray())
           }
       } catch (e: Exception) {
           // 記錄錯誤日誌,方便排查問題
           logger.error(e) { "Failed to make auto startup" }
       }
   }
   
   override fun isAutoStartUp(): Boolean {
       // 通過檢查 plist 文件是否存在來判斷是否已配置自啓動
       return pathProvider.userHome.resolve("Library/LaunchAgents/$plist").toFile().exists()
   }
   
   override fun removeAutoStartUp() {
       try {
           // 如果已配置自啓動,則刪除對應的 plist 文件來禁用自啓動
           if (isAutoStartUp()) {
               logger.info { "Remove auto startup" }
               pathProvider.userHome.resolve("Library/LaunchAgents/$plist").toFile().delete()
           }
       } catch (e: Exception) {
           logger.error(e) { "Failed to remove auto startup" }
       }
   }
}

2.3 配置説明

plist 文件的關鍵配置項：

• Label: 唯一標識符，使用應用的 Bundle ID
• ProgramArguments: 啓動程序路徑和參數
• RunAtLoad: 設置為 true 表示登錄時啓動

3. Windows 實現

3.1 實現原理

Windows 平台需要區分兩種安裝方式：

1. 普通安裝：通過註冊表 HKCU\Software\Microsoft\Windows\CurrentVersion\Run 實現
2. Microsoft Store：由於沙箱權限限制，使用 shell:appsFolder 協議啓動

3.2 具體實現

WindowsAppStartUpService

class WindowsAppStartUpService(
   appLaunchState: DesktopAppLaunchState,
   private val configManager: ConfigManager,
) : AppStartUpService {
   companion object {
       // PFN: Package Family Name, Microsoft Store 應用的唯一標識符
       // 格式為: {發佈者}.{應用名}_{發佈者ID}
       const val PFN = "ShenzhenCompileFutureTech.CrossPaste_gphsk9mrjnczc"
   }
   
   // 判斷是否是 Microsoft Store 安裝的應用
   private val isMicrosoftStore = appLaunchState.installFrom == MICROSOFT_STORE
   
   // 普通安裝版本的可執行文件路徑
   private val appExePath = DesktopAppPathProvider.pasteAppPath
       .resolve("bin")
       .resolve("CrossPaste.exe")
   
   // Microsoft Store 應用的啓動命令
   // 使用 shell:appsFolder 協議啓動 Store 應用,避免權限問題
   // 格式: explorer.exe shell:appsFolder\{PFN}!{AppName}
   private val microsoftStartup = "explorer.exe shell:appsFolder\\$PFN!$AppName"
   
   // 根據安裝類型返回對應的啓動命令
   private fun getRegValue(): String =
       if (isMicrosoftStore) microsoftStartup else appExePath.toString()
   
   override fun makeAutoStartUp() {
       try {
           if (!isAutoStartUp()) {
               // 通過註冊表實現開機自啓動
               // 路徑: HKCU\Software\Microsoft\Windows\CurrentVersion\Run
               // /v: 指定註冊表項名稱
               // /d: 指定要執行的命令
               // /f: 強制覆蓋已存在的值
               val command = "reg add \"HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\" " +
                   "/v \"$AppName\" /d \"${getRegValue()}\" /f"
               Runtime.getRuntime().exec(command)
           }
       } catch (e: Exception) {
           logger.error(e) { "Failed to make auto startup" }
       }
   }
   
   override fun isAutoStartUp(): Boolean {
       // 查詢註冊表中是否存在對應的自啓動項
       val command = "reg query \"HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run\" /v \"$AppName\""
       try {
           val process = Runtime.getRuntime().exec(command)
           // 讀取命令執行結果
           val reader = BufferedReader(InputStreamReader(process.inputStream))
           var line: String?
           while (reader.readLine().also { line = it } != null) {
               // REG_SZ 表示這是一個字符串值
               if (line!!.contains("REG_SZ")) {
                   // 提取註冊表項的值並比較
                   // 需要忽略大小寫,因為 Windows 路徑不區分大小寫
                   val registryValue = line.substringAfter("REG_SZ").trim()
                   return registryValue.equals(getRegValue(), ignoreCase = true)
               }
           }
       } catch (e: Exception) {
           logger.error(e) { "Failed to check auto startup status" }
       }
       return false
   }
}

4. Linux 實現

4.1 實現原理

Linux 桌面環境遵循 XDG Autostart 規範：

• 配置位置：~/.config/autostart/
• 文件格式：.desktop 文件
• 兼容性：支持主流桌面環境（GNOME、KDE、XFCE等）

4.2 具體實現

LinuxAppStartUpService

class LinuxAppStartUpService(private val configManager: ConfigManager) : AppStartUpService {
   // 使用 KotlinLogging 創建日誌記錄器
   private val logger: KLogger = KotlinLogging.logger {}
   
   // desktop 文件名,遵循 Linux 命名規範使用小寫
   private val desktopFile = "crosspaste.desktop"
   
   // 應用程序的可執行文件路徑
   private val appExePath = pathProvider.pasteAppPath
       .resolve("bin")
       .resolve("crosspaste")
   
   override fun makeAutoStartUp() {
       try {
           if (!isAutoStartUp()) {
               logger.info { "Make auto startup" }
               // 創建 desktop 文件到用户的自啓動目錄
               // ~/.config/autostart/ 是 XDG 規範定義的用户級自啓動目錄
               val desktopFilePath = pathProvider.userHome.resolve(".config/autostart/$desktopFile")
               filePersist.createOneFilePersist(desktopFilePath)
                   .saveBytes("""
                       [Desktop Entry]
                       # 聲明這是一個應用程序
                       Type=Application
                       # 應用程序顯示名稱
                       Name=CrossPaste
                       # 啓動命令和參數
                       Exec=$appExePath --minimize
                       # 應用程序分類
                       Categories=Utility
                       # 是否需要終端運行
                       Terminal=false
                       
                       # GNOME 桌面環境特定配置
                       # 啓用自動啓動
                       X-GNOME-Autostart-enabled=true
                       # 登錄後延遲 10 秒啓動,避免與其他程序衝突
                       X-GNOME-Autostart-Delay=10
                       
                       # KDE 桌面環境特定配置
                       # 指定在面板加載後啓動,確保系統托盤可用
                       X-KDE-autostart-after=panel
                   """.trimIndent().toByteArray())
           }
       } catch (e: Exception) {
           logger.error(e) { "Failed to make auto startup" }
       }
   }
   
   override fun isAutoStartUp(): Boolean {
       // 通過檢查 desktop 文件是否存在來判斷是否已配置自啓動
       // Linux 下的 .config/autostart 目錄是 XDG 規範定義的用户自啓動配置目錄
       return pathProvider.userHome.resolve(".config/autostart/$desktopFile").toFile().exists()
   }
}

4.3 配置説明

desktop 文件的關鍵配置項：

• Type: 必須為 Application
• Exec: 啓動命令和參數
• X-GNOME-Autostart-enabled: GNOME 環境的啓動控制
• X-GNOME-Autostart-Delay: 延遲啓動時間
• X-KDE-autostart-after: KDE 環境的啓動順序控制

5. 總結

通過 KMP 實現跨平台的開機自啓動，關鍵在於：

• 設計統一的接口抽象
• 理解並正確使用各平台的官方推薦方案
• 處理好平台特性差異
• 實現完善的錯誤處理和日誌記錄

這種設計既保證了代碼的可維護性，又能充分利用各平台的原生特性，為用户提供最佳的使用體驗。