极客工场

Appearance

共 905 字预计阅读约 3 分钟

docker 容器缺动态库：error while loading shared libraries 速查 ​

更新时间：2026-10-24。FAQ 速查页，面向「二进制在宿主机跑得好好的，塞进容器就秒崩」的同学。docker 容器缺动态库的报错语义很直白：动态链接器在启动时挨个解析可执行文件声明的依赖库，某个 .so 在容器的库搜索路径里不存在，程序连 main 都没进就被杀了。病灶收敛在六根轴上：精简镜像（alpine/distroless/scratch）本来就缺库、依赖库没拷进镜像、glibc 与 musl 两套 C 库不兼容、多阶段构建只拷了二进制没拷库、库在非标准路径而 LD_LIBRARY_PATH 没配、版本对不上（有库但符号版本不够）。本篇只讲运行期动态库缺失；镜像拉不下来看 docker 镜像找不到速查，起容器权限问题看 docker 权限被拒速查。

本文要回答的问题 ​

  • error while loading shared libraries: libxxx.so.1: cannot open shared object file 是什么意思？
  • 同一个二进制，为什么宿主机直接跑没事、进容器就报缺库？
  • alpine 镜像跑 glibc 编译的程序为什么连 libc.so 都找不到？
  • 多阶段构建里 COPY --from=builder 只拷了二进制，还缺什么？
  • 用 ldd 怎么列出一个二进制到底依赖哪些库？

一、报错原文与典型现象 ​

报错出现在容器启动瞬间，docker logs 里就能看到（工程路径以 /proj/demo 占位）：

bash
$ docker run --rm myapp:latest
/usr/local/bin/myapp: error while loading shared libraries: libssl.so.3: cannot open shared object file: No such file or directory
bash
# alpine 上跑 glibc 编译的 Go/Rust 静态链 libc 之外的程序：
$ docker run --rm myapp:alpine
exec /usr/local/bin/myapp: no such file or directory
# 文件明明在——缺的是动态加载器 /lib64/ld-linux-x86-64.so.2，报错更具迷惑性
bash
# 有库但版本不够的变体：
/usr/local/bin/myapp: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.34' not found (required by /usr/local/bin/myapp)

读报错抓两点：缺的是哪个库（报错里点名的 .so 文件），以及是完全没有还是版本不够——前者是文件不存在，后者是文件在但符号版本低，修法一个是补库、一个是换基底镜像。注意 alpine 场景的 no such file or directory 极具迷惑性：文件明明在，真正缺的是 glibc 的动态加载器。

二、病因处置速查表 ​

报错现象 / 场景可能原因快速验证处置
报缺具体某个 .so该库没装进镜像docker run --rm -it 镜像 ldd 二进制路径Dockerfile 里包管理器装对应库
distroless/scratch 起不来精简基底无任何库换 debian 基底对比静态编译，或把依赖库一起拷入
alpine 报 no such file（文件在）glibc 程序碰上 muslldd 输出 not a dynamic executable 或加载器缺失换 glibc 基底，或在 alpine 重装 musl 版
多阶段构建后缺库只 COPY 了二进制ldd 列出的库逐一对照镜像内文件把依赖 .so 一并 COPY 或换运行时基底
库装了但仍报缺库在非标准路径find / -name 'libxxx.so*' 找位置配 LD_LIBRARY_PATH 或 ldconfig 注册
version `GLIBC_x.yy' not found基底镜像 glibc 太旧ldd --version 看 glibc 版本换更新的基底镜像重编
宿主机好、容器崩宿主机碰巧装了该库同上 ldd 对照容器镜像自包含，不依赖宿主环境

三、排查决策图 ​

下面这张图是标准排查路线，颜色按角色区分：红是报错入口与命中的根因，蓝是排查动作，绿是通过分支，橙是修复动作，紫是防复发沉淀。

engineering/docker/ts-docker-undefined-symbol.md D2 示意图

读这张图抓住主线：一切从 ldd 出发——它把二进制声明的依赖逐条列出，not found 的就是缺口；然后看缺口是「没装」还是「装错了体系」（musl 对 glibc）。基底镜像的选择决定了你后面要补多少东西，这是排查的分水岭。

四、逐条排查展开 ​

排查第一命令：ldd。 它能直接列出一个动态链接二进制的全部依赖及解析结果：

bash
docker run --rm -it myapp:latest ldd /usr/local/bin/myapp
# 输出里出现 "not found" 的行就是缺口

scratch/distroless 镜像里没有 shell 和 ldd，这时在宿主机对同一二进制跑 ldd，或在 Dockerfile 构建阶段跑一次并把结果打进 CI 日志。

精简镜像缺库是最大来源。 alpine 只有 musl 这一套最小 C 库，openssl、libstdc++ 这些常用库都得自己装；distroless 更极端，连包管理器都没有。对应处置是在 Dockerfile 里显式装：

dockerfile
RUN apk add --no-cache libssl3 libstdc++     # alpine
# 或 debian 系：
RUN apt-get update && apt-get install -y --no-install-recommends libssl3 && rm -rf /var/lib/apt/lists/*

包名与库文件名的对应关系按发行版查（debian 用 apt-file search libssl.so.3，alpine 用 apk search）。

glibc 与 musl 是两套世界。 在 ubuntu 上编译的 C/C++ 程序默认动态链 glibc，拷进 alpine 后连动态加载器 /lib64/ld-linux-x86-64.so.2 都不存在，报的是 no such file or directory 而不是缺库——新手常被这个措辞带偏去查文件路径。处置二选一：换成 glibc 系基底（debian-slim）；或者干脆在 alpine 容器内用 musl 工具链重新编译。不要混装 glibc 兼容层救急，那是给以后埋雷。

多阶段构建：二进制之外还有库。 典型反例是 builder 阶段用完整镜像编译，运行阶段 COPY --from=builder /proj/demo/bin/myapp /usr/local/bin/ 就完事——二进制依赖的第三方 .so 全留在 builder 里了。修法是 ldd 列出依赖后，把不在运行时基底里的库一起 COPY：

dockerfile
COPY --from=builder /proj/demo/bin/myapp /usr/local/bin/myapp
COPY --from=builder /usr/local/lib/libfoo.so.1 /usr/local/lib/
RUN ldconfig

更省心的路线是运行阶段直接用与编译阶段同族的 slim 基底，让系统库天然对齐。

静态编译是 scratch 场景的正路。 Go 程序 CGO_ENABLED=0 go build、C/C++ 加 -static（glibc 静态链有 getaddrinfo 等坑， musl 静态链更干净），产出零依赖二进制后 FROM scratch 也能跑。代价是失去发行版安全更新通道的库补丁，要自行重编跟进 CVE。

库在非标准路径。 自己编译安装的库常落在 /usr/local/lib 而链接器缓存没刷新，表现为库文件明明在仍报缺。处置：ldconfig 刷新缓存，或在容器启动环境配 LD_LIBRARY_PATH=/usr/local/lib。前者是系统级注册，更稳。

没有 ldd 可用时的替代手段。 distroless/scratch 镜像里没有 ldd、没有 shell，docker run -it 镜像 sh 都进不去。三条替代路：在宿主机对同一二进制直接 ldd（前提是架构一致）；用 readelf -d 二进制 | grep NEEDED 列出声明的依赖库名——这个命令只读 ELF 头，不依赖目标系统有对应库；或在 Dockerfile 的 builder 阶段（有完整工具链）跑一次 ldd 并把输出写进构建日志，缺库问题在构建期就暴露而不是运行期。对「只在运行期才崩」的镜像，还可以 docker create + docker cp 把二进制拷出来到宿主机再分析，不用启动它。

GLIBC 版本不够的反向坑。 version 'GLIBC_2.34' not found 意味着你编译环境的 glibc 比运行基底新——降级编译环境或升级基底镜像，二选一。团队约定「编译基底与运行基底同版本族」能根除这类错。

五、规范做法与预防 ​

  • CI 加 ldd 自检：镜像构建完跑一次 ldd，有 not found 直接判构建失败，不让缺库镜像出门。
  • 基底镜像写进团队规范：谁用 alpine 谁负责 musl 兼容验证；默认推 debian-slim。
  • 编译与运行同基底族：builder 与 runtime 用同一发行版族的镜像，glibc 版本天然对齐。
  • 多阶段 COPY 清单化：Dockerfile 注释里写清「二进制 + 哪些库」，加依赖时同步更新。
  • 能静态就静态：Go/Rust 零依赖二进制优先，scratch/distroless 场景尤其。
  • 启动即崩先 logs：docker logs 第一条往往就是缺库原文，别先怀疑网络与配置。

这一篇在知识体系里的位置 ​

本篇是 docker 排错速查簇的依赖篇，定位「容器秒崩、报缺 .so」：拉取阶段的 manifest unknown 与限流看 docker 镜像找不到速查 与 docker 拉取限流速查；权限类报错看 docker 权限被拒速查；容器起来了但客户端连不上看 docker 容器端口连接被拒速查；daemon 与客户端版本打架看 docker 版本不兼容速查。ldd 看依赖、按基底选静态或动态，是容器化交付的通用底盘。

一句话总结 ​

docker 容器缺动态库先 docker logs 拿报错原文、ldd 列依赖找 not found 缺口；缺口分两类修——没装的库在 Dockerfile 用包管理器补齐，体系不对的（alpine musl 跑 glibc 程序、GLIBC 版本不够）换基底镜像或在对应工具链重编；多阶段构建别把依赖库落在 builder 里，非标准路径用 ldconfig 注册，scratch 场景走 CGO_ENABLED=0 或 -static 静态编译。CI 里给镜像加一道 ldd 全绿自检，这类报错即可基本绝迹。