ENTRYPOINT定义主程序,CMD提供默认参数,二者须用exec格式(JSON数组)才能正确拼接、传参和响应信号;ENTRYPOINT是固定外壳,CMD是可替换内芯,运行时新命令仅覆盖CMD。
核心就一条:entrypoint 定义主程序,cmd 提供它的默认参数。两者必须都用 exec 形式(也就是 json 数组写法),才能正确拼接、传递参数、响应信号。
ENTRYPOINT 是“固定外壳”,CMD 是“可换内芯”
容器启动时,真正执行的是 ENTRYPOINT + CMD 的组合。如果运行时传入新命令,CMD 被完全替换,但 ENTRYPOINT 始终不变。
- 写法示例:ENTRYPOINT ["node", "server.js"] + CMD ["--port", "3000"] → 启动时执行
node server.js --port 3000 - 运行时覆盖:
docker run myimg --port 8080 --env=prod→ 实际执行node server.js --port 8080 --env=prod,原 CMD 被丢弃 - 如果只写 CMD,没写 ENTRYPOINT,那 CMD 就是完整命令,运行时参数会直接覆盖整条 CMD
必须用 exec 形式,shell 形式会出问题
shell 形式(比如 ENTRYPOINT nginx -g "daemon off;")会启动一个 /bin/sh 进程来包裹命令,导致 PID 1 不是 nginx,信号(如 SIGTERM)无法正确传给主服务,容器可能无法优雅退出。
- ✅ 正确:
ENTRYPOINT ["nginx", "-g"]+CMD ["daemon off;"] - ❌ 危险:
ENTRYPOINT nginx -g "daemon off;"—— 此时 CMD 会被忽略,且 nginx 不在 PID 1 - exec 形式不经过 shell,环境变量不会自动展开,如需变量,应在脚本里处理,或改用入口脚本
推荐做法:用入口脚本统一收口
把复杂逻辑(比如配置生成、权限检查、环境适配)放进一个可执行脚本,再让 ENTRYPOINT 调它,CMD 传业务参数。
- 镜像中包含
entrypoint.sh,开头加#!/bin/sh,并chmod +x - Dockerfile 写:
ENTRYPOINT ["./entrypoint.sh"]+CMD ["start"] - 脚本末尾用
exec "$@"安全转发命令,既支持docker run myimg,也支持docker run myimg sh调试 - 这样既能保证主进程是 PID 1,又能灵活扩展启动逻辑
调试与临时接管技巧
容器起不来?别急着改镜像,先用运行时参数快速验证。
- 跳过原有 ENTRYPOINT:
docker run -it --entrypoint /bin/sh myimg,直接进 shell 查文件、看日志、手动执行启动命令 - 只换 CMD 参数:
docker run myimg --help,适合 CLI 类镜像 - 检查最终生效配置:
docker inspect myimg | grep -A 5 'Entrypoint\|Cmd'


















