Docker 容器启动后立即退出、反复重启，或出现“exec format error”“permission denied”“no such file or directory”等提示时，问题往往集中在 Entrypoint、启动脚本、文件权限、镜像架构和运行参数几个方面。🔧 本文提供一套从现象确认到根因定位的排查流程，帮助你避免无目的地反复构建镜像。
一、先判断容器处于什么状态
不要看到容器未运行就立即删除重建。首先执行 docker ps -a，查看容器是“Exited”还是“Restarting”，并记录退出码。常见退出码中，0 通常表示主进程正常结束；126 常与命令不可执行或权限不足有关；127 多表示命令不存在；137 可能是进程被强制终止，也可能与内存限制有关。
随后执行 docker logs 容器名 查看标准输出和错误输出。如果日志过长，可以使用 docker logs --tail 100 容器名；若需要观察启动过程，则使用 docker logs -f 容器名。日志为空并不代表程序没有报错，也可能是 Entrypoint 在应用启动前就已经执行失败。
进一步使用 docker inspect 容器名，重点检查 State、ExitCode、Error、OOMKilled、Path 和 Args。这样可以确认 Docker 实际执行的程序、传入的参数以及容器是否因内存不足而终止。相关字段说明可参考 来源链接 Inspect 官方文档。
二、理解 ENTRYPOINT 与 CMD 的组合关系
ENTRYPOINT 用于定义容器默认执行程序，CMD 通常为该程序提供默认参数。两者都推荐使用 JSON 数组形式，例如 ENTRYPOINT 设置为应用程序，CMD 设置为启动参数。执行 docker run 镜像 新参数 时，新参数通常会替换 CMD，但不会直接替换 ENTRYPOINT；如需临时替换入口程序，应使用 --entrypoint。
排查重点：不要只查看 Dockerfile 中的 CMD，还要检查基础镜像是否已经定义 ENTRYPOINT，以及 Compose、Kubernetes 或启动命令是否覆盖了原配置。
Shell 形式会通过命令解释器启动程序，可能影响环境变量展开和信号传递；Exec 形式则直接运行指定可执行文件，更适合作为容器主进程。两种形式的具体行为可查看 ENTRYPOINT 官方说明。📘
三、逐项排查常见 Entrypoint 错误
1. no such file or directory
该错误不一定表示脚本本身不存在。还应检查脚本第一行指定的解释器是否存在，例如精简镜像可能没有 Bash，只有 /bin/sh；同时确认 COPY 的目标路径、WORKDIR 和 ENTRYPOINT 使用的路径一致。相对路径容易受工作目录影响，入口脚本建议使用明确的绝对路径。
2. permission denied
入口文件存在但不能执行时，检查镜像构建阶段是否执行了 chmod +x。还要关注 Dockerfile 的 USER 指令：切换到普通用户后，该用户必须对脚本、应用文件及相关目录具有读取和执行权限。若宿主机通过卷挂载覆盖了镜像内文件，挂载后文件的权限和内容也可能与构建时不同。
3. exec format error
此错误常见于脚本缺少 Shebang、脚本采用 Windows 的 CRLF 换行，或镜像与宿主机 CPU 架构不匹配。可在构建前将脚本转换为 LF 换行，并确认第一行类似 #!/bin/sh。对于跨平台构建，还应通过 docker image inspect 镜像名 查看 Architecture，并核对构建和运行平台。
4. 环境变量或参数异常
启动脚本经常依赖数据库地址、端口、配置路径和密钥变量。可以通过 docker inspect 检查容器最终获得的环境变量，但分享输出时应先隐藏敏感信息。脚本中引用变量时建议加双引号，并对必填变量进行启动前校验，避免空值被拼接成错误命令。
四、容器无法常驻时如何进入环境调试
容器主进程已经退出时，无法直接使用 docker exec，因为该命令只能在运行中的容器内启动新进程，详见 docker exec 官方文档。此时可以基于同一镜像启动临时容器，并覆盖入口程序，例如使用 docker run --rm -it --entrypoint /bin/sh 镜像名。
进入临时环境后，依次确认入口文件是否存在、执行权限是否正确、解释器和依赖库是否齐全，并手动运行原启动命令。🧪 如果镜像过于精简而没有 Shell，可以在构建阶段增加专用调试镜像，不建议为了临时排错把大量工具永久加入生产镜像。
五、检查挂载、Compose 与编排层覆盖
镜像单独运行正常，但通过 Docker Compose 启动失败时，应检查 compose 配置中的 entrypoint、command、environment、working_dir 和 volumes。尤其是目录挂载：宿主机空目录可能覆盖镜像内已经复制好的程序或配置文件，最终导致入口脚本找不到目标文件。
可以执行 docker compose config 查看变量替换和多份配置合并后的最终结果，再与镜像原始配置对照。若启用了自动重启策略，建议排查期间暂时停用或限制重启，避免容器进入快速重启循环，使关键错误信息难以观察。
六、推荐的标准排查顺序
- 确认状态：使用 docker ps -a 记录退出状态和退出码。
- 读取日志：检查应用输出，以及 Docker 返回的入口执行错误。
- 检查配置：通过 docker inspect 核对 Path、Args、环境变量和挂载。
- 覆盖入口：启动临时 Shell，验证文件、权限、解释器与依赖。
- 排除格式问题：检查 Shebang、LF 换行和 CPU 架构。
- 核对覆盖项：检查 Compose 或编排平台是否修改了入口和参数。
- 重新构建：必要时使用明确的构建日志，并谨慎禁用缓存验证修改。
七、从源头降低启动失败概率
- 优先采用 Exec 形式编写 ENTRYPOINT 和 CMD，减少 Shell 解析差异。
- 在构建阶段统一脚本换行格式并设置可执行权限。
- 入口脚本使用 set -e 等错误处理机制，并输出清晰的失败原因。
- 启动前校验必需环境变量、配置文件和依赖服务地址。
- 固定并记录基础镜像版本，避免环境变化导致结果不可复现。
- 为生产镜像和调试镜像设置不同构建阶段，兼顾体积与可维护性。
总结
Docker 容器启动失败并不等同于应用程序本身故障。有效的排查方法是沿着“容器状态—日志—实际启动配置—文件与解释器—运行环境—外部覆盖”逐层缩小范围。✅ 面对 Entrypoint 错误时，优先相信 inspect 展示的最终配置，而不是仅凭 Dockerfile 推测；再通过覆盖入口启动临时环境手动验证，通常能够快速定位权限、路径、换行格式、架构或参数问题。
