Lunar 4.1.1 修复深度解析：Launch at Login 空列表崩溃的根因与防御策略

本文基于 Lunar 仓库的发布说明 ReleaseNotes/4.1.1.md 展开：该版本的核心修复只有一条——修复"登录时启动"（Launch at Login）空列表导致的崩溃。文章将带领读者梳理 Lunar 实现"开机自启"的完整技术链路（SMAppService 与 LSSharedFileList 双轨注册），结合源码逐层还原这条崩溃的成因与防御写法，并给出可供自测验证的入口。读完你将掌握 macOS 登录启动项 API 的常见坑位，以及 Lunar 在真实项目中如何为它们兜底。

一、4.1.1 修复内容速览：一行 Fixes 背后的问题

原文档 ReleaseNotes/4.1.1.md 全文内容如下：

## Fixes

* Fix crash because of launch at login empty list

这一条目同样出现在仓库的 CHANGELOG.md 中（# 4.1.1 章节），与发行说明完全一致，可以确认这是 4.1.1 版本的唯一修复项：

# 4.1.1
## Fixes

* Fix crash because of launch at login empty list

从版本序列看，4.1.0 刚引入了 Sync Mode 对 Pro Display XDR / LG UltraFine 显示器源的支持、模式禁用原因的 Tooltip、网络控制与 DDC 的"重置"按钮等新特性，而 4.1.1 紧随其后、专注消除一个高影响的启动崩溃；随后的 4.1.2 又修复了内置显示器检测与媒体键处理逻辑。这说明 4.1.1 是一个典型的"及时止损"补丁版本。

这条崩溃与 Lunar 的常驻菜单栏 + 开机自启机制强相关：Lunar 作为调整外接显示器亮度、对比度、音量的系统级应用，默认希望在用户登录后自动运行（否则自适应亮度等核心能力会随重启失效）。一旦"登录时启动"处理路径崩溃，应用可能在启动流程早期就退出，直接影响全部功能，因此被列为该版本唯一且优先的修复。

二、理解"Launch at Login"：Lunar 的开机自启功能全链路

要读懂这条修复，先要看清"登录时启动"在 Lunar 中是如何从设置项一路走到系统 API 的。

2.1 设置项：startAtLogin

Lunar 的偏好设置通过 Defaults 持久化，startAtLogin 是其中的布尔开关，定义于 DataStore.swift 的默认值列表，并在 DataStore.swift 通过 cacheKey(.startAtLogin) 建立缓存键。

为了响应设置变化，仓库在 DataStore.swift 定义了专门的发布者：

let startAtLoginPublisher = pub(.startAtLogin)

pub 是基于 Defaults.publisher 封装的事件流（见 DataStore.swift）：丢弃首个初始值、去重，并在新旧值不一致时才发出事件。这意味着只要用户在界面上切换该开关，订阅方就会收到一次 KeyChange<Bool>。

2.2 UI 入口：两处可切换

用户触达这个开关的界面有两条：

• QuickActions 菜单（常驻菜单栏弹出的快捷面板）：在 QuickActionsMenuView.swift 中以 Toggle("Launch at login", isOn: $startAtLogin) 呈现，其状态由 QuickActionsMenuView.swift 的 @Default(.startAtLogin) var startAtLogin 双向绑定；
• 设置窗口的 Storyboard：在 Main.storyboard 中通过 Cocoa Binding 将控件绑定到 values.startAtLogin。

2.3 核心调度：handleDaemon() 的双轨注册

真正的系统级注册动作集中在 AppDelegate 的 handleDaemon()。它被 AppDelegate.swift 在应用启动流程（applicationDidFinishLaunching 附近）中调用，同时订阅了 startAtLoginPublisher，因此启动时按当前设置执行一次，之后每次用户切换开关都会再次执行：

func handleDaemon() {
    let handler = { (shouldStartAtLogin: Bool) in
        guard let appPath = p(Bundle.main.bundlePath) else { return }

        let appDir = (try? appPath.parent.realpath()) ?? appPath.parent
        guard appDir.components.starts(with: self.APP_DIR) || appDir.components.starts(with: self.SVAPP_DIR) else { return }

        if #available(macOS 13.0, *),
           withTimeout(5.seconds, name: "SMAppService", {
               if shouldStartAtLogin {
                   try SMAppService.mainApp.register()
               } else {
                   try SMAppService.mainApp.unregister()
               }
               return true
           }) == true
        {
            log.debug("SMAppService registered")
        } else {
            LaunchAtLoginController().setLaunchAtLogin(shouldStartAtLogin, for: appPath.url)
            log.debug("LaunchAtLoginController registered")
        }
    }

    handler(CachedDefaults[.startAtLogin])
    startAtLoginPublisher.sink { change in
        handler(change.newValue)
    }.store(in: &observers)
}

这段代码包含了几个与"崩溃防护"直接相关的关键设计：

1. 路径守卫：guard let appPath = p(Bundle.main.bundlePath) 与 guard appDir.components.starts(with: APP_DIR || SVAPP_DIR) 双保险。其中 APP_DIR 对应 /Applications、SVAPP_DIR 对应 /System/Volumes/Data/Applications（定义于 AppDelegate.swift）。只有应用确实安装在 Applications 目录时才执行注册——否则直接返回，避免对非正常安装路径执行系统级操作。
2. 双轨策略：在 macOS 13+ 上优先使用系统推荐的 SMAppService.mainApp.register()/unregister()，并包裹 withTimeout(5.seconds, ...) 限时；一旦新 API 不可用、超时或抛错，立即回退到基于 LSSharedFileList 的旧式 LaunchAtLoginController。两种成功路径都会输出对应日志（SMAppService registered / LaunchAtLoginController registered），这也为排障提供了直接线索。

三、崩溃根因剖析：登录启动项"空列表"发生了什么

3.1 旧式实现：LaunchAtLoginController

回退路径对应的 Objective-C 类位于 LaunchAtLoginController.h 与 LaunchAtLoginController.m，由 Lunar-Bridging-Header.h 导入 Swift 工程。

其核心 API 是 macOS 经典的会话登录项列表（Session Login Items）：

• init 中通过 LSSharedFileListCreate(NULL, kLSSharedFileListSessionLoginItems, NULL) 取得当前用户的登录项列表，并注册 LSSharedFileListAddObserver 监听其变化（LaunchAtLoginController.m）；
• findItemWithURL:inFileList: 对列表做 LSSharedFileListCopySnapshot 快照，逐项 LSSharedFileListItemResolve 解析出 URL 并与目标 URL 比对（LaunchAtLoginController.m）；
• setLaunchAtLogin:forURL: 根据开关状态调用 LSSharedFileListInsertItemURL 插入或 LSSharedFileListItemRemove 移除（LaunchAtLoginController.m）；
• 对外暴露的属性 launchAtLogin 与 setLaunchAtLogin: 封装了上述过程（LaunchAtLoginController.m）。

3.2 同类实现的 Swift 版本：LoginServiceKit

仓库的 LoginServiceKit.swift 是同一 API 族的另一份 Swift 实现（源自 Clipy Project 的 LoginServiceKit，底层同样使用 LSSharedFileList），其中暴露了一个非常关键的细节——空列表的显式保护：

let loginItemsListSnapshot: CFArray? = LSSharedFileListCopySnapshot(loginItemList, nil)?.takeRetainedValue()
guard let loginItems = loginItemsListSnapshot as? [LSSharedFileListItem], let last = loginItems.last else { return false }

LSSharedFileListInsertItemURL(loginItemList, last, nil, nil, url, nil, nil)
return true

这段来自 LoginServiceKit.swift 的 addLoginItems(at:) 值得逐行分析：

• LSSharedFileListCopySnapshot 返回的 CFArray 被桥接为 [LSSharedFileListItem]；
• 如果用户的登录项列表恰好为空（例如全新系统、从未手动添加过任何登录项），快照数组为空，loginItems.last 为 nil；
• 代码用 guard let ... let last = loginItems.last else { return false } 在插入前兜底——列表为空时直接返回 false 而非继续执行。

这正是 4.1.1 修复所针对的核心场景：在登录项列表为空（empty list）时，旧代码直接对 nil 位置执行插入或未加保护的快照解包，触发崩溃。当前仓库中的这两处实现（LoginServiceKit 的 guard 与 LaunchAtLoginController 的 for-in 快照遍历）都可以看作该修复落地后的防御形态：从源码结构可以推断，4.1.1 通过在"取最后一个登录项 / 遍历快照"等环节补充空列表保护，消除了这条启动期崩溃路径。

3.3 为什么会走到空列表分支

从实现链路反推，触发"空列表"的最常见场景是：

1. 全新安装 / 全新用户账户：当前 macOS 会话的登录项列表初始为空；
2. 用户从未手动添加过任何登录启动应用（Lunar 自己尚未成功注册）；
3. 此时若用户打开 Lunar 的"Launch at login"开关（或 Lunar 启动时按当前设置尝试注册），LSSharedFileListCopySnapshot 得到的就是空数组；
4. 若代码不检查 last/空数组而直接继续，就可能发生数组越界、nil 位置插入或桥接解包失败，最终表现为应用启动即崩溃——而这恰恰是"登录时启动"功能本应防止的失败模式，因此被 4.1.1 列为最高优先级修复。

四、验证与排查：如何确认登录启动功能正常

由于当前仓库即包含修复后的实现，读者可以从以下几个可验证的观察点确认"登录时启动"功能处于健康状态：

1. 日志：打开 Lunar 日志，开启/关闭"Launch at login"开关后，应看到 SMAppService registered（macOS 13+ 成功路径）或 LaunchAtLoginController registered（回退路径），对应 AppDelegate.swift 中的 log.debug 输出；
2. 开关状态：在 QuickActions 菜单的 "App info" 区域（QuickActionsMenuView.swift）观察 Launch at login 复选框（QuickActionsMenuView.swift）能否正常切换并在重启 Lunar 后保持；
3. 系统侧确认：在 macOS 的"系统设置 → 通用 → 登录项"中应能看到 Lunar 条目；对 macOS 13+ 用户而言，SMAppService.mainApp 注册成功后也会出现在该列表中；
4. 路径前提：Lunar 必须安装在 /Applications（APP_DIR）或 /System/Volumes/Data/Applications（SVAPP_DIR）下才会执行注册（AppDelegate.swift），若从其他路径运行，handleDaemon 会静默跳过注册——这属于设计上的路径守卫，而非故障。

五、工程启示：从单行修复看防御式系统 API 调用

4.1.1 的这条修复虽然只有一行，但映射出 macOS 系统级 API 调用的三个通用工程原则：

1. 对系统返回的集合永远假设"可能为空"：LSSharedFileListCopySnapshot 这类返回 CFArray 的 API，语义上不保证非空；从当前仓库代码（LoginServiceKit.swift 的 guard let last = loginItems.last）可以看到，正确的防御是"解包 + 空检查 + 提前返回"，而不是默认有值。
2. 新 API 优先、旧 API 兜底、全程限时：handleDaemon 对 SMAppService 的调用套了 withTimeout(5.seconds, ...)，失败即回退 LSSharedFileList，避免单一 API 的异常阻塞或拖垮启动流程。
3. 对外部环境做前置守卫：只有应用位于 Applications 目录（AppDelegate.swift）才执行系统注册，把不可控的系统状态（安装路径、登录项现状）排除在执行路径之外。

六、结语

从 ReleaseNotes/4.1.1.md 的一行 Fixes 出发，本文完整还原了 Lunar 登录自启功能的实现骨架：设置项 startAtLogin（DataStore.swift）→ 发布者 startAtLoginPublisher（DataStore.swift）→ 界面开关（QuickActionsMenuView.swift）→ 双轨注册 handleDaemon（AppDelegate.swift）→ 系统 API（SMAppService / LSSharedFileList）。4.1.1 的修复正是为这条链路上"登录项列表为空"这一现实状态补齐了防御，避免了"为了自启而崩溃"的悖论。对 macOS 开发者而言，这也是阅读真实项目中系统服务注册代码的一份高价值案例：永远把系统状态当作不可信任的输入来编写防御逻辑。