第13章 - 跨平台与 Cgo-free 构建

RobotGo 的一大卖点是“一份代码，跨三大平台”。然而由于传统模式依赖 Cgo 和系统库，跨平台编译（尤其是交叉编译）一直是痛点。近年来 RobotGo 引入了纯 Go（Cgo-free）后端，针对 Windows、Linux Wayland 与 libei 提供了无需 GCC 的构建方式，极大改善了部署体验。本章讲解跨平台编码技巧与 Cgo-free 构建。

13.1 跨平台编码：处理平台差异

虽然 RobotGo 的 API 在各平台一致，但有些行为本身就因平台而异，最典型的就是修饰键。编写跨平台脚本时，应根据 runtime.GOOS 动态处理这些差异。

package main

import (
    "runtime"

    "github.com/go-vgo/robotgo"
)

// 返回当前平台的“主修饰键”：macOS 用 cmd，其余用 ctrl
func cmdKey() string {
    if runtime.GOOS == "darwin" {
        return "cmd"
    }
    return "ctrl"
}

func main() {
    // 跨平台的复制粘贴
    robotgo.KeyTap("c", cmdKey())
    robotgo.KeyTap("v", cmdKey())
}

runtime.GOOS 的常见取值："windows"、"darwin"（macOS）、"linux"。基于它，你可以为不同平台选择不同的快捷键、路径分隔符或行为分支。

13.1.1 平台特定文件

Go 的构建约束（build constraints）也能帮助组织平台相关代码。例如把 macOS 专属逻辑放进 xxx_darwin.go，Windows 逻辑放进 xxx_windows.go，Go 工具链会根据目标平台自动选择编译哪个文件。

13.2 传统 Cgo 模式的交叉编译困境

传统模式下 RobotGo 依赖 Cgo，而 Cgo 交叉编译需要目标平台的 C 交叉编译工具链与系统库头文件，配置相当繁琐。例如在 Linux 上编译 Windows 版 RobotGo，需要 MinGW 交叉工具链；编译 macOS 版则几乎不可行（需要 macOS SDK）。

正因如此，传统模式下最稳妥的做法是在目标平台的机器（或 CI runner）上原生编译：Windows 上编 Windows 版，macOS 上编 macOS 版，Linux 上编 Linux 版。RobotGo 官方文档也提供了交叉编译的专门说明（见仓库 docs/install.md 的 Cross-Compiling 章节）。

13.3 Cgo-free 后端概览

为了解决上述痛点，RobotGo 提供了纯 Go 实现的后端。它们暴露与 robotgo 完全相同的 API，因此你的业务代码无需改动，只需在构建时加上对应的构建标签（build tag），并设置 CGO_ENABLED=0：

后端	构建标签	Go 包	平台
Windows（Cgo-free）	`win`	`github.com/go-vgo/robotgo/win`	Windows
Wayland（wlroots）	`wayland`	`github.com/go-vgo/robotgo/wayland`	Linux（Sway/Hyprland/Wayfire 等）
libei（GNOME/KDE 门户）	`libei`	`github.com/go-vgo/robotgo/libei`	Linux（GNOME/KDE）

这些后端的最大价值在于：无需 GCC、MinGW 或 X11 头文件即可编译，并支持 CGO_ENABLED=0 的交叉编译。这对于在 CI 中构建、分发桌面工具来说是巨大的便利。需要注意它们目前仍是实验性（experimental）的。

13.4 Cgo-free 构建命令

13.4.1 Windows（无需 Cgo / MinGW）

CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -tags win ./...

在 win 构建标签下，默认的 Cgo/Win32 后端被排除，所有调用会被转发到纯 Go 的 win 包。这意味着你可以在 Linux 或 macOS 上交叉编译出 Windows 版可执行文件，而无需任何 C 工具链。

13.4.2 Wayland（wlroots 合成器）

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -tags wayland ./...

在 wayland 标签下，Cgo/X11 后端被排除，调用转发到纯 Go 的 wayland 包。它适用于基于 wlroots 的合成器（Sway、Hyprland、Wayfire 等），通过下列 Wayland 协议工作：

zwlr_virtual_pointer_v1             鼠标控制
zwp_virtual_keyboard_v1             键盘控制
zwlr_screencopy_v1                  屏幕截图
zwlr_foreign_toplevel_management_v1 窗口管理

重要限制：GNOME 与 KDE 默认不支持这些 wlroots 协议，因此 wayland 后端在 GNOME/KDE 上无法工作——那种情况要用下面的 libei 后端。

13.4.3 libei（GNOME / KDE）

CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -tags libei ./...

在 libei 标签下，Cgo/X11 后端与 wlroots Wayland 后端都被排除，调用转发到纯 Go 的 libei 包。它通过 freedesktop 的 xdg-desktop-portal 的 RemoteDesktop 接口驱动输入，因此能在 GNOME 与 KDE 上工作。运行时需要：

xdg-desktop-portal                门户 D-Bus 服务
xdg-desktop-portal-gnome / -kde   你桌面对应的门户后端

重要限制：libei 后端只处理鼠标和键盘输入；截图与窗口管理会返回 ErrNotSupported。也就是说，如果你的自动化重度依赖截图/图像识别，libei 后端目前并不适合。

13.5 三种 Linux 后端如何取舍

Linux 桌面环境碎片化，选择后端时可按下面的决策思路：

传统 X11（Cgo）：经典选择，功能最全（输入、截图、窗口都支持），但需要 GCC 与 X11 开发库，且在纯 Wayland 会话下可能受限（通过 XWayland 兼容）。
wayland 后端（Cgo-free）：用于 wlroots 系合成器，功能较全（含截图与窗口管理），无需 C 库。但不支持 GNOME/KDE。
libei 后端（Cgo-free）：用于 GNOME/KDE，无需 C 库，但只支持输入，不支持截图与窗口管理。

简言之：要截图就别指望 libei；用 GNOME/KDE 就别指望 wlroots 的 wayland 后端；想要最全功能且能装 C 库，传统 X11 仍是稳妥之选。

13.6 在 CI 中构建多平台产物

借助 Cgo-free 后端，可以在单一 Linux CI 环境中交叉编译多个目标。示例思路（以 shell 为例）：

# Windows 版（纯 Go）
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -tags win -o dist/app-windows-amd64.exe ./...

# Linux Wayland 版
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -tags wayland -o dist/app-linux-wayland ./...

# Linux libei 版（GNOME/KDE）
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -tags libei -o dist/app-linux-libei ./...

而 macOS 版与传统 X11 Linux 版仍建议在对应平台原生构建。

13.7 ARM 架构支持

RobotGo 同时支持 x86-amd64 与 arm64。要构建 ARM 版本，设置 GOARCH=arm64 即可，例如为 Apple Silicon 或树莓派构建：

# Cgo-free 的 Linux arm64（Wayland）
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -tags wayland ./...

传统 Cgo 模式下为 ARM 构建则需要对应架构的 C 工具链，通常在 ARM 设备上原生编译最省事。

13.8 实战技巧与注意事项

业务代码不变：Cgo-free 后端与主库 API 完全一致，切换后端只改构建标签与 CGO_ENABLED，无需改业务逻辑。
实验性提醒：Cgo-free 后端仍是实验性的，上生产前请在目标环境充分测试。
能力差异：libei 不支持截图/窗口管理；选后端前先确认你的功能需求与后端能力匹配。
修饰键跨平台：用 runtime.GOOS 处理 macOS 与 Windows/Linux 的修饰键差异。
原生构建兜底：macOS 版以及功能最全的 X11 版，优先在对应平台原生编译。
查阅官方交叉编译文档：传统 Cgo 模式的交叉编译细节，参考仓库 docs/install.md 的 Cross-Compiling 部分。

13.9 小结

本章我们讨论了 RobotGo 的跨平台开发：用 runtime.GOOS 与构建约束处理平台差异，理解了传统 Cgo 模式交叉编译的困境，并重点学习了新引入的 Cgo-free 后端——win、wayland、libei 三种纯 Go 后端的构建标签、适用平台、协议依赖与能力限制，以及它们在 CI 多平台构建和 ARM 支持上的价值。下一章我们将把全书所学融会贯通，做一个综合实战项目。