在不支持的平台进行交叉编译GO

发表于 分类于 ， ，
Go 语言的交叉编译机制，重点说明了通过 GOOS、GOARCH 与关闭 cgo 实现多平台可执行文件构建的方法，覆盖 Linux、Windows、macOS 及 ARM 等常见场景。

Go 语言交叉编译基础指南

一、什么是交叉编译

交叉编译（Cross Compilation） 是指：

在一个平台（宿主机）上，编译生成可在另一个平台（目标机）运行的可执行文件。

例如：

  • 在 Linux x86_64 上编译 Windows exe
  • 在 macOS 上编译 Linux ARM 程序
  • 在 amd64 机器上编译 ARM / ARM64 程序

Go 天生支持交叉编译，这是它在云原生、容器化、嵌入式等领域广受欢迎的重要原因之一。

二、Go 交叉编译的核心机制

Go 的交叉编译主要通过以下 三个环境变量 控制：

变量 含义
GOOS 目标操作系统
GOARCH 目标 CPU 架构
CGO_ENABLED 是否启用 cgo（本文固定为 0）

本文 默认关闭 cgo，确保跨平台编译简单、稳定。

三、常见 GOOS / GOARCH 组合

1️ 常见操作系统（GOOS）

GOOS 说明
linux Linux
windows Windows
darwin macOS
freebsd FreeBSD

2️ 常见 CPU 架构（GOARCH）

GOARCH 说明
amd64 x86_64
arm64 ARM 64 位（Apple Silicon / ARM Server）
arm ARM 32 位
386 x86 32 位

四、最基础的交叉编译命令

示例：编译 Linux 可执行文件（amd64）

1
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o app-linux

示例：编译 Windows 可执行文件

1
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o app.exe

示例：编译 macOS（Apple Silicon）

1
CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o app-macos-arm64

五、常见平台交叉编译示例合集

Linux → Windows

1
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o app.exe

Linux → macOS（Intel）

1
CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o app-macos

macOS → Linux ARM（如服务器 / NAS）

1
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o app-linux-arm64

x86 → ARM（树莓派）

1
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -o app-pi

GOARM 常见值：

  • 6：ARMv6
  • 7：ARMv7（最常用）

六、一次性查看 Go 支持的全部平台

1
go tool dist list

输出示例：

1
2
3
4
5
linux/amd64
linux/arm64
windows/amd64
darwin/arm64
...

七、构建多平台产物（推荐脚本方式）

示例：构建 Linux / Windows / macOS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
#!/bin/bash

set -e

APP=demo

build() {
  GOOS=$1
  GOARCH=$2
  OUTPUT=$3

  echo "Building $GOOS/$GOARCH..."
  CGO_ENABLED=0 GOOS=$GOOS GOARCH=$GOARCH go build -o $OUTPUT
}

build linux amd64 ${APP}-linux-amd64
build windows amd64 ${APP}-windows-amd64.exe
build darwin arm64 ${APP}-macos-arm64

八、交叉编译的注意事项

1 文件名差异

  • Windows：需要 .exe
  • Linux / macOS：无后缀

2️运行平台限制

  • 交叉编译 只能保证能生成文件

  • 不能保证逻辑在目标平台一定正确

  • 涉及：

    • 文件路径
    • 系统调用
    • 权限模型

3️ 推荐关闭 cgo

1
CGO_ENABLED=0

九、构建不再官方支持平台

必要前提：必须要有目标平台的GCC编译器

1. 配置目标GCC路径

1
2
3
4
5
6
ENV ARM_PATH=/data/gcc/toolchain-arm_cortex-a9_gcc-13.1.0_musl_eabi
ENV PATH=$PATH:$ARM_PATH/bin
ENV CC=arm-linux-gcc
ENV CXX=arm-linux-g++
ENV AR=arm-linux-ar
ENV RANLIB=arm-linux-ranlib

2. 使用构建命令编译

1
env GOOS=linux GOARCH=arm GOARM=5 CGO_ENABLED=0 CC=${CC} go build  -ldflags "-w -s"  -o builds/main

3. 错误处理

错误 Illegal instruction

  • 大致含义是指很有可能是由于CPU不支持VFP特性导致的问题
  • 指定 GOARM=5
  • GOARM=5 GOARCH=arm GOOS=linux CGO_ENABLED=0 go build -ldflags “-extldflags ‘-static’ -w -s “ -o main-armv5