Go 的 -buildmode=c-archive 默认为每个包生成完整运行时，导致多 archive 链接时符号重复；正确做法是通过一个空 main 包统一导入所有目标包，并用 go install -buildmode=c-archive 构建单一归档文件，实现完全静态链接。
go 的 `-buildmode=c-archive` 默认为每个包生成完整运行时，导致多 archive 链接时符号重复；正确做法是通过一个空 `main` 包统一导入所有目标包，并用 `go install -buildmode=c-archive` 构建单一归档文件，实现完全静态链接。
在嵌入式或轻量部署场景中，将多个 Go 功能模块以 C 兼容方式静态集成到一个最终可执行文件中，是常见且关键的需求。然而，直接对多个独立的 Go 包分别执行 go build -buildmode=c-archive，再用 GCC 链接（如 gcc test.c a.a b.a），必然触发 multiple definition of runtime.* 等链接错误——因为每个 .a 文件都包含完整的 Go 运行时（go.o、runtime.a、libc.a 等），而 C 链接器无法自动去重这些全局符号。
根本原因在于：c-archive 模式并非设计用于“模块化拼装”，而是面向“单入口、全功能”的静态库封装。go build 也不支持多包输入生成单 archive，因此试图手动剥离 go.o 或合并多个 .a 是不可靠且易出错的（正如问题中所述，go.o 同时包含运行时和用户代码）。
✅ 正确解法：统一构建入口 + 包级导入 + go install
核心思路是放弃“多个 archive”，转而构造一个逻辑上只负责聚合、不包含业务逻辑的主包，通过 _ "path/to/pkg" 形式隐式导入所有需暴露的 Go 子包。这些子包必须是 main 包（含 //export 函数）或 library 包（导出函数并被 main 引用），且均启用 //export 声明。
示例结构如下：
$GOPATH/src/mylib/
├── main.go # 聚合入口（空 main）
├── foo/
│ └── foo.go # package foo; //export foo_func
└── bar/
└── bar.go # package bar; //export bar_func
main.go 内容：
package main
import (
_ "mylib/foo"
_ "mylib/bar"
)
func main() {} // 必须存在，但无需逻辑
构建命令（关键！必须用 go install，而非 go build）：
go install -buildmode=c-archive mylib
执行后，Go 工具链会在 $GOPATH/pkg/
C 端调用示例（test.c）：
#include "mylib.h" // 单一头文件
int main() {
foo_func(); // 来自 foo/
bar_func(); // 来自 bar/
return 0;
}
编译链接（仅需一个 .a）：
gcc test.c -o test mylib.a -lpthread -ldl
⚠️ 注意事项：
- 必须使用 go install：go build -buildmode=c-archive 对非 main 包或路径不支持此聚合行为，而 go install 会正确解析依赖图并构建完整归档。
- 导入必须加 _：_ "mylib/foo" 表示仅触发包初始化（注册 //export 函数），避免 unused import 错误；若用 import "mylib/foo"，Go 会因无显式引用报错。
- 子包需合规：每个被导入的子包必须包含至少一个 //export 函数，且不能有 main() 函数（否则冲突）。
- 跨平台兼容性：该方案原生支持 Linux/macOS/Windows，无需 GNU ld 特定技巧；若需进一步裁剪（如禁用 CGO、GC），可追加 -ldflags="-s -w" 或 CGO_ENABLED=0。
- 头文件管理：生成的 mylib.h 已包含全部导出函数声明，C 代码无需分别包含 foo.h/bar.h，简化了接口管理。
总结：这不是 hack，而是 Go 官方支持的模块化静态集成模式。它兼顾了代码解耦（各功能仍位于独立子包）、部署极简（单二进制、零依赖）与链接安全（单一运行时实例）。对于大型项目，可配合脚本自动生成聚合 main.go，实现“按需组合、一键构建”。
