必须显式设置GOOS和GOARCH，否则编译出的二进制无法在嵌入式设备运行；Linux设备需禁用CGO并静态链接，MCU则必须用TinyGo且严格遵循项目结构与target名称。

GOOS 和 GOARCH 必须显式设置，否则编译出的二进制根本跑不起来

嵌入式设备资源有限，Go 代码不能直接用 go build 编译后扔上去就完事。你得清楚区分两种场景：一种是目标设备运行 Linux（如树莓派、ARM64 开发板），另一种是裸机 MCU（如 ESP32、Pico）。两者工具链、约束条件、失败表现完全不同——混用会浪费大量时间在“程序烧进去了但板子没反应”这种问题上。

Linux 系统级嵌入式设备：交叉编译必须禁用 CGO

你在 x86_64 机器上编译，想让程序在 ARM64 的嵌入式 Linux 上跑，最常见错误就是忘了关 CGO_ENABLED。

• CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -ldflags="-s -w" -o server server.go 是基础命令，缺一不可
• 运行 file server 检查输出里是否含 statically linked；如果出现 dynamically linked，说明 CGO 没关干净，或者用了隐式依赖 C 库的包（比如 os/user、默认 DNS 解析）
• 若必须用 net/http，加构建 tag：-tags netgo，强制走 Go 原生 DNS，避免调用 libc
• 第三方包如 github.com/mattn/go-sqlite3 默认启用 CGO，要么换纯 Go 实现（如 modernc.org/sqlite），要么用 -tags sqlite_nomysql

裸机 MCU（ESP32/Pico）必须用 TinyGo，且 target 名字不能缩写

go build 对 MCU 完全无效。TinyGo 是唯一可行路径，但它对项目结构极其敏感。

Golang Spf13 Viper

Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。

下载

立即学习“go语言免费学习笔记（深入）”；

• main.go 必须放在 go.mod 同级根目录，不能在 ./cmd/ 或子文件夹里；首行必须是 package main，不能带下划线或 test 后缀
• tinygo build -target=esp32s3 -o firmware.uf2 main.go 中的 esp32s3 是精确名称，写成 esp32 或 s3 都会导致烧录后无响应——芯片启动代码错位，UART 不吐字，LED 不闪
• ESP32 系列要严格区分：esp32（S2）、esp32c3、esp32s3，分区表、USB 引脚、Flash 映射全不同
• 串口没输出？先检查是否调了 uart.Configure(machine.UARTConfig{BaudRate: 115200}) —— TinyGo 不自动初始化外设，漏这行等于没通电

标准库和第三方包在嵌入式中不是“能用就行”

很多 Go 代码在桌面环境跑得好好的，一交叉编译就报错，根源在于底层 syscall 或平台特性缺失。

• syscall.Reboot 在 arm64 Linux 上未实现，编译直接失败；类似地，syscall.Getpid 在某些 MCU target 上也不存在
• 用 time.Sleep 要小心：部分 MCU target 主频低，time.Millisecond * 10 可能实际卡住几百毫秒，调试时建议先加短延时验证流程
• 第三方包若含 //go:build cgo 或引用 <sys></sys> 等头文件，基本无法在裸机环境用；优先选标注 purego 的替代实现
• HTTP 服务在 ESP32 上可用，但别指望跑 Gin 或 Echo —— 它们依赖反射和大量内存，xiaozhi-esp32-server-golang 这类精简框架才是正解

验证必须回到目标设备做最小闭环

交叉编译成功 ≠ 能跑通。嵌入式环境暴露问题的方式很原始：权限拒绝、段错误、串口静默、LED 不亮。

• Linux 设备上先 chmod +x server，再 ./server；若提示 Permission denied，可能是文件系统挂载时用了 noexec，改用 mount -o remount,exec /
• MCU 烧录后没反应？别急着换线，先用 tinygo flash -target=xxx -port /dev/ttyACM0 显式指定端口，避免自动识别错设备
• UART 输出乱码？确认波特率匹配，且开发板 USB-to-Serial 芯片驱动已加载（尤其 macOS 上 CH340 需手动装驱动）
• 最有效的验证方式：删掉所有业务逻辑，只留 LED 闪烁或 UART 打印 "OK"，确保硬件链路通了再往上加功能

真正卡住人的从来不是语法，而是 target 名字拼错、CGO_ENABLED 漏关、UART 忘 Configure 这几行代码。这些地方没有容错，也不会报明确错误，只会沉默——你得知道该去哪查。