Github Actions运行Go测试遇X11 DISPLAY环境变量缺失错误求助

问题 #

配置GitHub Actions测试基于Ebiten的Go游戏时，构建环节正常，但测试阶段报错，提示X11的DISPLAY环境变量缺失，导致GLFW库初始化失败。

错误日志 #

Run cd tests && go test . -v
go: downloading github.com/davecgh/go-spew v1.1.1
go: downloading github.com/pmezard/go-difflib v1.0.0
go: downloading gopkg.in/yaml.v3 v3.0.1
2024/03/14 23:49:05 PlatformError: X11: The DISPLAY environment variable is missing
panic: NotInitialized: The GLFW library is not initialized

goroutine 1 [running]:
github.com/hajimehoshi/ebiten/v2/internal/cglfw.acceptError({0x0, 0x0, 0x10004?})
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/cglfw/error.go:184 +0x1f4
github.com/hajimehoshi/ebiten/v2/internal/cglfw.panicError(...)
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/cglfw/error.go:195
github.com/hajimehoshi/ebiten/v2/internal/cglfw.WindowHint(0x0?, 0x0?)
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/cglfw/window.go:317 +0x34
github.com/hajimehoshi/ebiten/v2/internal/glfw.WindowHint(...)
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/glfw/glfw_cglfw.go:347
github.com/hajimehoshi/ebiten/v2/internal/ui.initialize()
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/ui/ui_glfw.go:174 +0x36
github.com/hajimehoshi/ebiten/v2/internal/ui.init.2()
    /home/runner/go/pkg/mod/github.com/hajimehoshi/ebiten/v2@v2.6.6/internal/ui/ui_glfw.go:159 +0x13
FAIL    github.com/Arkadiusz4/meteor-maverick-game/tests    0.028s
FAIL
Error: Process completed with exit code 1.

已尝试的无效方法 #

• 在GitHub Actions工作流中安装X11相关依赖（libxrandr-dev、libgl1-mesa-dev等）
• 在main.go中手动设置DISPLAY环境变量为:0

解决方案 #

GitHub Actions的Ubuntu runner是无头环境（无图形界面），Ebiten依赖的GLFW库需要X11显示环境才能初始化，因此需要创建虚拟X服务器或启用Ebiten无头模式。

方法1：使用xvfb创建虚拟X服务器 #

1. 在工作流的依赖安装步骤中添加xvfb：

sudo apt-get install xvfb libxrandr-dev libgl1-mesa-dev libxcursor-dev libxinerama-dev libxi-dev libxxf86vm-dev xorg-dev mesa-utils

2. 修改测试步骤，用xvfb-run包裹测试命令，它会自动设置DISPLAY变量并启动虚拟X服务器：

- name: Testing, testing
  run: xvfb-run -a go test ./tests -v

修改后的完整工作流文件：

name: Go

on:
  push:
    branches: [ "main" ]
  pull_request:
    branches: [ "main" ]

jobs:

  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        go-version: [ '1.21.x' ]

    steps:
      - uses: actions/checkout@v3

      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21.3'

      - name: Display Go version
        run: go version

      - name: Install dependencies
        run: |
          go get github.com/hajimehoshi/ebiten/v2
          go get github.com/stretchr/testify
          sudo apt-get update
          sudo apt-get install xvfb libxrandr-dev libgl1-mesa-dev libxcursor-dev libxinerama-dev libxi-dev libxxf86vm-dev xorg-dev mesa-utils

      - name: Build
        run: go build -v ./...

      - name: Testing, testing
        run: xvfb-run -a go test ./tests -v

方法2：启用Ebiten无头模式（适用于无需渲染的测试） #

如果你的测试不需要实际图形渲染，可以设置环境变量EBITEN_HEADLESS=1让Ebiten在无头模式下运行，无需X11环境：

修改测试步骤：

- name: Testing, testing
  env:
    EBITEN_HEADLESS: 1
  run: cd tests && go test . -v

注意：此方法仅适用于不依赖实际窗口渲染的测试，如果测试需要验证渲染结果，还是推荐使用xvfb方法。

内容的提问来源于stack exchange，提问作者ArQczeg14