先确认CGO_ENABLED=1是否启用，否则go build跳过C代码导致链接失败；再通过#cgo LDFLAGS显式指定-L库路径和-l库名；最后用LD_LIBRARY_PATH或-Wl,-rpath确保运行时能找到动态库。
go build 时找不到动态库，先确认 CGO_ENABLED 是否开启
Go 默认禁用 CGO，哪怕代码里写了 import "C"，go build 也会跳过 C 部分、直接报链接失败或 undefined reference。这不是路径问题，是根本没编译 C 代码。
必须显式启用：CGO_ENABLED=1 go build。Linux/macOS 直接加前缀；Windows PowerShell 用 $env:CGO_ENABLED="1"，CMD 用 set CGO_ENABLED=1。
- 交叉编译时（如 macOS → Linux），
CGO_ENABLED=0是常态，但这时你压根不能用动态库——纯 Go 模式不支持dlopen -
go env CGO_ENABLED能验证当前值，输出1才算生效 - 某些 CI 环境默认关 CGO，得在构建脚本里显式打开，不能只依赖本地配置
动态库路径没被链接器看到，靠 #cgo LDFLAGS 显式声明
Go 不会自动扫描 ./lib 或 /usr/local/lib，即使库文件就在旁边。链接器只认 #cgo LDFLAGS 里写的路径和名字。
比如你的 libapi.so 在项目根目录下的 lib/ 子目录中，且函数定义在 api.h 里：
/* #cgo LDFLAGS: -L./lib -lapi #include "api.h" */ import "C"
-
-L./lib告诉链接器去./lib找库，注意路径是相对于go build执行位置的，不是相对于.go文件 -
-lapi对应的是libapi.so（Linux/macOS）或api.dll（Windows），不是文件全名 - Windows 下若用 MinGW，库名可能是
libapi.a或api.dll.a，-lapi依然适用；但若用 MSVC 工具链，则需改用.lib导入库 +ldflags指向.lib文件路径
运行时报 libxxx.so: cannot open shared object file，是运行时路径缺失
编译通过 ≠ 运行成功。Linux 下动态库加载器（ld-linux）默认只查 /lib、/usr/lib 和 LD_LIBRARY_PATH，不会看编译时的 -L 路径。
- 临时解决：运行前设环境变量
LD_LIBRARY_PATH=./lib:$LD_LIBRARY_PATH ./myapp - 永久嵌入：用
-Wl,-rpath,$ORIGIN/lib把运行时搜索路径硬编码进二进制（$ORIGIN表示可执行文件所在目录）：/* #cgo LDFLAGS: -L./lib -lapi -Wl,-rpath,$ORIGIN/lib */ - macOS 对应的是
-rpath @loader_path/lib，Windows 则依赖PATH或同目录放 DLL - 用
ldd ./myapp（Linux）或otool -l ./myapp | grep -A2 LC_RPATH（macOS）验证 rpath 是否写入成功
replace 本地模块后调用 C 动态库，路径容易错乱
当主项目用 replace yourlib => ../yourlib 引入本地模块，而该模块内部又依赖 libxxx.so，问题就来了：编译主项目时，#cgo LDFLAGS 的相对路径（如 -L./lib）是按主项目根目录解析的，不是按被 replace 的模块根目录。
- 最稳做法：把动态库统一放在主项目根目录的
lib/下，并在所有用到它的.go文件里都写-L./lib - 避免在被 replace 的模块里写绝对路径（如
-L/home/user/project/yourlib/lib），那会破坏可移植性 - 如果模块必须自带库，考虑改用静态库（
.a）并用-lxxx直接链接，绕过运行时路径问题 -
go mod vendor不会复制动态库文件，vendor 只管 Go 源码，这点必须手动补全
动态库路径问题从来不是单一环节的事：编译要找得到，链接要认得着，运行时还得加载得上。三个阶段的路径含义完全不同，混用或假设“写一个 -L 就到处有效”是绝大多数失败的根源。
