使用 xgo 进行含 cgo 依赖（如 gokogiri）的 go 项目跨平台编译时，常因目标环境缺失 iconv.h 等 c 头文件而失败；根本解法是显式提供可交叉编译的 libiconv 源码包，而非本地路径或预编译二进制。
使用 xgo 进行含 cgo 依赖（如 gokogiri）的 go 项目跨平台编译时，常因目标环境缺失 iconv.h 等 c 头文件而失败；根本解法是显式提供可交叉编译的 libiconv 源码包，而非本地路径或预编译二进制。
在基于 gokogiri（现多维护为 github.com/moovweb/gokogiri 或其衍生库）的 Go 项目中启用 CGO 交叉编译时，你遇到的错误：
/usr/include/libxml2/libxml/encoding.h:28:19: fatal error: iconv.h: No such file or directory
本质上并非 xgo 配置错误，而是 libxml2 在交叉构建时依赖 libiconv 提供字符编码转换能力，而 xgo 默认未自动集成该依赖的源码级交叉编译支持。关键在于：xgo 不接受本地已安装的 macOS Homebrew 版本（如 /usr/local/Cellar/libiconv/1.14/），因为它无法将 macOS 的 .dylib 或头文件适配到 Linux/ARM 等目标平台——这违背了交叉编译“工具链与目标环境严格一致”的基本原则。
✅ 正确做法是：通过 --deps 参数传入 libiconv 的官方源码压缩包 URL，让 xgo 在容器内自动下载、配置（./configure --host=...）、编译并安装该库到目标平台的 sysroot 中。
✅ 推荐解决方案（实测有效）
./xgo \ --deps https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.17.tar.gz \ --go 1.22 \ mydomain.com/test/test-app
⚠️ 注意事项：
- 使用 libiconv-1.17.tar.gz（或 ≥1.15）而非旧版，因其对现代交叉工具链兼容性更好；
- --go 1.22 显式指定 Go 版本，避免 xgo 默认旧版引发兼容问题；
- URL 必须为 .tar.gz 格式，xgo 仅支持 tarball 形式的源码依赖（见 xgo 官方文档）；
- 不要使用 --deps /path/to/local/libiconv —— 该路径会被忽略或导致静默失效，日志中 “Dependency already cached” 仅表示本地缓存存在，不代表它被正确用于目标平台构建。
? 为什么 --deps /usr/local/Cellar/... 无效？
xgo 的 --deps 机制设计初衷是全自动构建跨平台依赖：它会在 Docker 容器中解压源码、执行 ./configure --host=aarch64-linux-gnu（依目标 GOOS/GOARCH 自动推导）、make && make install，最终将头文件（include/iconv.h）和静态库（lib/libiconv.a）注入目标 sysroot。而本地 Homebrew 路径指向的是 macOS x86_64 动态库，既无 iconv.h 的目标平台版本，也无法链接到 Linux ARM64 的 libxml2。
?️ 进阶建议：确保 libxml2 同步适配
gokogiri 实际依赖 libxml2，而后者又依赖 libiconv。若仍报错，可叠加指定 libxml2 源码：
./xgo \ --deps https://ftp.gnu.org/pub/gnu/libiconv/libiconv-1.17.tar.gz \ --deps https://gitlab.gnome.org/GNOME/libxml2/-/archive/v2.13.2/libxml2-v2.13.2.tar.gz \ mydomain.com/test/test-app
xgo 会按顺序构建依赖，确保 libiconv 先就位，再供 libxml2 链接使用。
✅ 替代方案：禁用 CGO（仅限纯功能降级场景）
若项目不强依赖 gokogiri 的 XML 解析性能，且可接受 net/http 等标准库退化行为（如 DNS 解析改用 Go 原生实现），可临时关闭 CGO：
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o test-app .
⚠️ 但注意：gokogiri 本身强制依赖 C 代码，CGO_ENABLED=0 将直接导致 import "C" 编译失败，因此此方案不适用于 gokogiri 场景——它仅适用于完全不含 import "C" 且未间接引入 net, os/user 等隐式 CGO 包的项目。
? 总结
| 场景 | 推荐方式 | 关键命令 |
|---|---|---|
| ✅ 含 gokogiri 等 CGO 依赖的跨平台编译 | 提供 libiconv 源码 URL | ./xgo --deps https://ftp.gnu.org/.../libiconv-1.17.tar.gz ... |
| ❌ 使用本地 Homebrew 路径 | 无效，会被忽略 | --deps /usr/local/Cellar/... → 不推荐 |
| ⚠️ 构建失败排查 | 查看 xgo 容器内 configure 日志 | 添加 -v 参数启用详细输出 |
坚持“源码驱动、容器隔离、目标平台原生构建”原则，即可稳定解决 iconv.h not found 类交叉编译顽疾。
