用 libghostty-spm 把真实终端嵌进 SwiftUI——三个你绕不过去的坑

想在一个原生 macOS SwiftUI 应用里嵌入一个「真实的」终端——Metal 渲染、真 PTY、真 login shell——最省力的路是社区包 libghostty-spm（github.com/Lakr233/libghostty-spm）。包本身质量不错，但 API 极年轻（2026 年 3 月才出现），文档稀疏，我在实际集成时踩了三个坑，整理在这里。

现象

第一次把 TerminalSurfaceView 塞进视图层级，编译通过，App 启动，窗口一片空白。既没有崩溃日志，也没有任何 Console 输出。拖拽窗口甚至能看到 Metal 图层在闪，但就是不渲染字符。

坑一：必须 `exact` 锁版本，不能 `upToNextMinor`

libghostty-spm 的公开 API 是「随 Ghostty 主库迭代推进」的——作者在 README 里明说 API 尚不稳定。用 .upToNextMinor 约束下次 swift package update 可能拉到 breaking change，但不报任何编译错误（Swift 泛型协议的弱类型兼容性会掩盖），直到运行时才崩溃。

坑：宽松版本约束 = 静默破坏

用 .upToNextMinor("1.2.3") 看似保守，但这个包的 minor 版里可能重命名 public struct。正确做法是 .exact("1.2.3")，升级时手动 Review changelog 再移版本号。

// Package.swift
.package(
    url: "https://github.com/Lakr233/libghostty-spm.git",
    exact: "1.2.3"   // 写死，不写 upToNextMinor
)

坑二：空白渲染——`configuration` 必须在 `onAppear` 里写

TerminalSurfaceView 内部靠 TerminalViewState 驱动。如果你在初始化时就赋值 state.configuration（而不是等 onAppear），SwiftUI 的 View 生命周期会让 Metal layer 还没 attach 到 window 就触发 PTY fork，fork 成功但渲染管线尚未就绪，结果是 PTY 活着、字符不渲染。

坑：提前赋值 configuration = 空白窗口

不要在 @StateObject 初始化或 init() 里设置 configuration，必须等 onAppear，此时 Metal layer 已经挂载完毕。

import SwiftUI
import GhosttyTerminal
 
struct TerminalSurface: View {
    let workingDirectory: String?
    @StateObject private var state = TerminalViewState()
 
    var body: some View {
        TerminalSurfaceView(context: state)
            .onAppear {
                // 必须在这里赋值，不能提前
                state.configuration = TerminalSurfaceOptions(
                    backend: .exec,
                    workingDirectory: workingDirectory
                )
            }
    }
}

正解：onAppear 延迟赋值

把 configuration 的赋值放到 onAppear 回调，确保 Metal 渲染管线已就绪再 fork PTY。

坑三：无法截图时，靠进程树验活

macOS 15 移除了 CGWindowListCreateImage 的跨 Space 截图能力。如果 App 窗口在另一个 Desktop Space，headless 脚本拍出来是全黑图，根本无法判断终端是否真的渲染了。

正确的验证方式：.exec backend 会 fork 一条真实的 login ... exec -l /bin/zsh 链路，数子进程即可。

APP_PID=$(pgrep -f "YourApp.app/Contents/MacOS/YourApp")
ps -axo pid,ppid,command | awk -v a="$APP_PID" '$2==a'
# 每个 TerminalSurfaceView 对应一条：
# <pid> <APP_PID> /usr/bin/login -flp <user> /bin/bash --noprofile --norc -c exec -l /bin/zsh

N 个 Surface = N 条 login shell 子进程，数量对上即验证通过。

顺带一提：LaunchServices 名称碰撞

如果 /Applications 里曾装过同名旧 App（比如旧的 Tauri 构建），open <路径> 和 osascript activate "YourApp" 可能静默激活的是旧版本而不是你刚编译的。调试时直接跑二进制：

"$APP/Contents/MacOS/YourApp" &

或者用 bundle ID 激活：tell application id "com.xxx.YourApp" to activate。

排查要点

| 症状 | 先检查 | |------|--------| | 空白窗口，无崩溃 | configuration 是否在 onAppear 里赋值 | | 编译通过但运行时 crash | SPM 依赖版本是否用 exact 锁住 | | 进程树里看不到 login shell | backend 是否写了 .exec 而不是 .inMemory | | headless 截图全黑 | 换进程树计数方式验活 |

一句话外卖

libghostty-spm 的 API 还年轻——锁死版本、延迟赋值 configuration、用子进程树而非截图验活，这三条能绕开 80% 的踩坑场景。