Docker容器启动失败的常见原因分析

我们在开发部署的时候，用 Docker 打包环境，理论上是"我装好了你就能跑"。但理想很丰满，现实往往一 docker run 下去就翻车了。

今天来盘点一下我实际工作中经常遇到的 Docker 容器启动失败的常见原因，顺便给点 debug 的小技巧，能让你从"容器起不来"到"稳稳跑起来"。

---

常见场景 1：镜像构建失败，容器压根没起来

很多人以为"容器起不来"就是 docker run 的问题，其实很多时候是在 docker build 阶段就翻车了。

典型报错：

failed to solve with frontend dockerfile.v0: failed to read dockerfile: open /path/to/Dockerfile: no such file or directory

排查办法：

• 检查 Dockerfile 路径是否正确；

• docker build 命令中 -f 指定的路径是不是错了；

• COPY 和 ADD 的源路径是不是写对了，尤其是"相对路径"。

小贴士：

如果你在构建时卡住了，可以加上 --progress=plain 和 --no-cache 看得更清楚一点：

docker build --progress=plain --no-cache -t myimage .

---

常见场景 2：容器秒退，没有主进程 or 主进程挂了

这个是真·经典问题。

典型表现：

容器刚启动立刻就退出了。比如：

docker run myimage
# 几秒后
docker ps -a
# 状态为 Exited (1)

原因分析：

• 没有前台进程 。容器是以主进程是否在运行为准的，如果你在 Dockerfile 里 CMD ["nginx"] 启了个守护进程（daemon），容器就直接退出了。

• 程序一启动就报错，直接崩了。

怎么查：

docker logs <container-id>

如果啥都没有，或者一眨眼就退了，可以加个 -it，手动起个 bash 看：

docker run -it myimage /bin/bash

---

常见场景 3：端口冲突 / 未暴露端口

报错不一定明确：

有时候你在宿主机开了某个端口（比如本地的 nginx 占了 80），你再用 -p 80:80 就起不来了。

解决办法：

• 用 docker ps 看看是不是端口已经被别的容器占用了；

• 改用别的端口，比如：

  docker run -p 8080:80 myimage

---

常见场景 4：环境变量配置错误

比如你 Dockerfile 里写了：

ENV DB_HOST=$DB_HOST

抱歉，这个语法会把 $DB_HOST 当成字面量（字符串），并不会替换成你主机环境里的变量。

正确姿势：

ARG DB_HOST
ENV DB_HOST=${DB_HOST}

然后 build 时传参：

docker build --build-arg DB_HOST=127.0.0.1 -t myimage .

或者更简单地，在 run 的时候用 -e 指定：

docker run -e DB_HOST=127.0.0.1 myimage

---

常见场景 5：文件权限问题

如果你在容器里挂载了宿主机的文件夹：

docker run -v /my/data:/app/data myimage

结果程序直接报权限错误，比如：

Permission denied: '/app/data/output.log'

原因：

容器里运行的用户没权限写这个挂载目录。

解决方法：

• 用 chown 改下宿主机的目录权限；

• 或者加上 --user 参数运行容器：

  docker run --user (id -u):(id -g) -v /my/data:/app/data myimage

---

最后一个大招：用 --entrypoint 开 bash 进去排查

如果你啥都试了都没搞明白，那最后一个招就是手动进去看：

docker run --entrypoint /bin/bash -it myimage

进去看看有没有路径写错，权限不对，环境变量没设之类的，通常都能找到线索。

---

小结

场景	排查思路
镜像构建失败	看 Dockerfile 路径、COPY 路径
容器秒退	docker logs，看主进程是否正常运行
端口冲突	换端口 or 检查是否被占用
环境变量问题	检查是否正确设置 ENV / ARG
文件权限问题	用 --user 或调整挂载目录权限
看不出问题	用 --entrypoint /bin/bash 手动排查

---

写到这里你应该对"容器为啥起不来"有些眉目了。总之，多动手、多看 log、多试试 -it 进去看现场，慢慢你就会像老中医一样一眼看出问题所在了。

有别的翻车现场也欢迎留言分享，大家一起做个不怕起不来容器的狠人。