退出码 127 的含义
退出码 127 表示容器内找不到要执行的命令：镜像里没有安装、PATH 里没有该目录，或入口脚本的 shebang 指向了不存在的解释器。它与 125（Docker 层失败）的区别是容器已经起来了，失败发生在容器内部。
基本信息
| 含义 | 容器内的命令不存在 |
|---|---|
| 常见原因 | 镜像未安装、PATH 不含该目录、shebang 目标缺失 |
| 排查手段 | 查看 PATH、核对命令是否存在、看入口脚本首行 |
| 易混淆 | 与 125（Docker 层失败）不同 |
| 区分提示 | 别与应用自定义返回码混用 |
典型使用场景
- 容器启动即退出并提示命令不存在时定位
- 基础镜像换发行版后命令名或路径变化
- 入口脚本 shebang 指向了不存在的解释器
- 流水线里构建产物没有被放进镜像
- 排查 PATH 被覆盖导致命令不可见
排查命令是否可用
排查命令是否可用
docker run --rm alpine curl --version # 精简镜像里没有 curl
docker run --rm --entrypoint sh alpine -c 'command -v curl || echo missing'
docker run --rm --entrypoint sh alpine -c 'echo $PATH'
docker run --rm --entrypoint sh alpine -c 'head -1 /docker-entrypoint.sh' # 检查 shebang线索与处理方向
| 线索 | 原因 | 处理方向 |
|---|---|---|
| 命令确实不存在 | 镜像未安装 | 构建期补装 |
| 命令在但调不到 | PATH 不含该目录 | 用绝对路径或调整 PATH |
| 入口脚本报错 | shebang 目标缺失 | 改 shebang 或换基础镜像 |
| 本地正常线上异常 | 镜像版本不同 | 核对实际使用的镜像 |
宿主上命令可用不代表容器里可用，镜像的 PATH 与包集合是另一套。
shebang 写成 bash 但镜像是只有 sh 的精简发行版时，同样会以找不到命令的形式失败。
排查时先确认命令是否存在于镜像，再看 PATH，顺序反了会多绕一圈。
应用自定义的返回码可能与这个约定值撞车，脚本判断时最好同时看日志内容。
构建产物没被打进镜像时也会表现成找不到命令，核对镜像内容比反复改配置更快。
把常用排查工具装进镜像的调试变体，日常排障会省下不少时间。
排查时先在容器内手动执行一遍目标命令并同时打印 PATH，两条信息放在一起看，多数情况一次就能定性。