第02章 - 环境准备与安装配置

RobotGo 在传统模式下是一个基于 Cgo 的库，这意味着它在编译时需要调用本机的 C 编译器并链接系统级的图形、输入相关库。因此，正确地准备开发环境是顺利使用 RobotGo 的第一步，也是初学者最容易踩坑的地方。本章将按操作系统分别讲解依赖安装、Go 模块初始化以及常见安装问题的排查。

2.1 通用前置条件

无论你使用哪个操作系统，传统（Cgo）模式下都需要确保以下两项基础工具已正确安装：

• Golang：建议使用较新的稳定版本（Go 1.11+ 以支持 Go Modules，实际推荐 Go 1.20 及以上）。
• GCC：用于编译 RobotGo 依赖的 C 代码。

你可以通过以下命令验证它们是否就绪：

go version
gcc --version

如果两条命令都能正确输出版本信息，说明基础工具链已经准备好。

2.2 macOS 环境配置

2.2.1 安装 Go 与编译工具

在 macOS 上推荐使用 Homebrew 安装 Go：

brew install go

RobotGo 在 macOS 上还需要 Xcode 命令行工具来提供 C 编译能力：

xcode-select --install

2.2.2 授予系统权限

这是 macOS 上最关键、也最容易被忽略的一步。由于 RobotGo 需要控制鼠标键盘、读取屏幕，macOS 的隐私保护机制会拦截这些操作，除非你显式授权。

请打开：

系统设置 → 隐私与安全性（Privacy & Security）

然后在以下两项中，把你运行 RobotGo 程序的终端（例如 Terminal、iTerm2）或你的 IDE 添加进去并勾选：

• 辅助功能（Accessibility）：允许控制鼠标键盘。
• 屏幕录制与系统音频录制（Screen & System Audio Recording）：允许截图与读取屏幕像素。

注意：如果你在 IDE 里直接运行程序，需要授权的是 IDE；如果在终端里 go run，需要授权的是该终端应用。授权后通常需要重启对应应用才能生效。如果程序无法移动鼠标或截图全黑，几乎都是权限没配好。

2.3 Windows 环境配置

2.3.1 安装 Go

winget install Golang.go

2.3.2 安装 GCC 工具链（传统 Cgo 模式）

Windows 上推荐使用 LLVM-MinGW：

winget install MartinStorsjo.LLVM-MinGW.UCRT

或者使用 WinLibs 提供的 Mingw-w64：

winget install BrechtSanders.WinLibs.POSIX.UCRT

你也可以手动下载 Mingw-w64，解压后将其 bin 目录（例如 C:\mingw64\bin）添加到系统环境变量 Path 中，使得 gcc 命令可以在命令行中直接调用。

提示：如果你使用的不是 Mingw-w64 而是其他 GCC，当需要用到 bitmap 位图相关功能时，可能需要自行编译 libpng。对大多数用户来说，使用 Mingw-w64 / LLVM-MinGW 是最省事的选择。

2.3.3 纯 Go（Cgo-free）方式

如果你希望避免安装 GCC，Windows 上可以使用 RobotGo 提供的纯 Go win 后端，通过构建标签 win 并设置 CGO_ENABLED=0 来编译。这部分详见第 13 章。

2.4 Linux 环境配置

Linux 下的依赖最多，因为不同功能（剪贴板、位图、事件监听）依赖不同的系统库。下面以 Ubuntu 和 Fedora 为例。

2.4.1 Ubuntu / Debian

# 安装 Go（也可使用 snap）
sudo snap install go --classic

# GCC 与基础开发库
sudo apt install gcc libc6-dev

# X11 相关（鼠标键盘控制、截图的核心依赖）
sudo apt install libx11-dev xorg-dev libxtst-dev

# 剪贴板支持
sudo apt install xsel xclip

# 位图（Bitmap）支持
sudo apt install libpng++-dev

# 全局事件监听（GoHook）支持
sudo apt install xcb libxcb-xkb-dev x11-xkb-utils libx11-xcb-dev \
    libxkbcommon-x11-dev libxkbcommon-dev

2.4.2 Fedora

# X11
sudo dnf install libXtst-devel

# 剪贴板
sudo dnf install xsel xclip

# 位图
sudo dnf install libpng-devel

# 全局事件监听
sudo dnf install libxkbcommon-devel libxkbcommon-x11-devel xkbcomp-devel
# Fedora 34 以下还需要：xorg-x11-xkb-utils-devel

2.4.3 Wayland 与 libei（纯 Go 后端）

如果你的 Linux 桌面运行在 Wayland 下，RobotGo 提供了两套纯 Go（Cgo-free）后端，无需上述 C 库：

• wayland 后端：适用于基于 wlroots 的合成器（Sway、Hyprland、Wayfire 等），通过 zwlr_virtual_pointer_v1、zwp_virtual_keyboard_v1、zwlr_screencopy_v1、zwlr_foreign_toplevel_management_v1 等协议工作。注意 GNOME 与 KDE 默认不支持这些协议。
• libei 后端：通过 freedesktop 的 xdg-desktop-portal 的 RemoteDesktop 接口驱动输入，因此可在 GNOME 与 KDE 上工作。它需要安装 xdg-desktop-portal 以及对应桌面的后端（xdg-desktop-portal-gnome 或 xdg-desktop-portal-kde）。注意 libei 后端只处理鼠标键盘输入，截图和窗口管理会返回 ErrNotSupported。

这两套后端的构建方式见第 13 章。

2.5 安装 RobotGo

2.5.1 初始化 Go 模块

在你的项目目录中先初始化一个 Go module：

mkdir robotgo-demo && cd robotgo-demo
go mod init robotgo-demo

2.5.2 引入 RobotGo

在 Go 1.11+ 的模块模式下，只需在代码中导入即可，Go 会在构建时自动下载：

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

或者手动执行：

go get github.com/go-vgo/robotgo

2.5.3 更新 RobotGo

go get -u github.com/go-vgo/robotgo

历史提示：Go 1.10.x 存在 C 文件编译缓存问题（golang #24355），以及 go mod vendor 的相关问题（golang #26366）。如果你使用的是非常老的 Go 版本并遇到怪异的编译错误，升级 Go 通常能解决。

2.6 验证安装

创建一个最小程序来验证环境是否就绪：

package main

import (
    "fmt"

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

func main() {
    sx, sy := robotgo.GetScreenSize()
    fmt.Println("屏幕尺寸:", sx, sy)

    x, y := robotgo.Location()
    fmt.Println("当前鼠标位置:", x, y)
}

运行：

go run main.go

如果能正确打印出屏幕尺寸和鼠标坐标，说明 RobotGo 已经安装并工作正常。

2.7 常见安装问题排查

下面整理一些高频问题及解决思路。

2.7.1 png.h: No such file or directory

这是缺少 libpng 开发头文件导致的，常见于 Linux 或自定义 GCC 的 Windows 环境。解决方法：

• Ubuntu：sudo apt install libpng++-dev
• Fedora：sudo dnf install libpng-devel
• Windows：使用 Mingw-w64 / LLVM-MinGW，或自行编译 libpng。

官方在 issues/47 中有专门讨论。

2.7.2 找不到 X11/extensions/XTest.h（Linux）

说明缺少 XTest 扩展开发库：

sudo apt install libxtst-dev xorg-dev libx11-dev

2.7.3 exec: "gcc": executable file not found

说明 CGO_ENABLED 处于开启状态但没有可用的 GCC。要么安装 GCC，要么改用纯 Go 后端（设置 CGO_ENABLED=0 并加上对应构建标签，见第 13 章）。

2.7.4 macOS 上程序运行无效果

绝大多数是权限问题。请确认运行程序的终端 / IDE 已在“辅助功能”和“屏幕录制”中授权，并重启该应用。

2.7.5 编译缓慢

由于 Cgo 需要编译大量 C 代码，首次构建 RobotGo 会比纯 Go 项目慢很多，这是正常现象。后续增量构建会因缓存而变快。

2.8 小结

本章我们针对 macOS、Windows、Linux 三大平台分别完成了 RobotGo 的依赖安装与权限配置，初始化了 Go 模块并引入了 RobotGo，最后通过一个最小程序验证了环境，并整理了常见安装问题的排查方法。环境就绪后，下一章我们将真正写出第一个完整的桌面自动化程序，把鼠标、键盘、截图等能力串起来。