Dockerfile 使用技巧

本文翻译自我的英文博客，最新修订内容可随时参考：Dockerfile使用技巧

通常我们会在项目根目录编写 Dockerfile，它是描述镜像构建流程的配置文件。官方文档提供了详细语法说明，但实际使用中需要注意一些关键细节，尤其是 CMD 和 ENTRYPOINT 的区别。

一、Dockerfile 核心要点

1. 多CMD指令：undefined若定义多个 CMD，仅有最后一个生效。建议将多个命令写入脚本文件（如 start.sh），通过 CMD ["./start.sh"] 执行。
2. 容器启动机制：undefinedDocker 容器不支持 systemd，其主进程即为应用进程。容器生命周期与主进程绑定，主进程退出则容器终止。
   • 错误示例：CMD service nginx start（service 会在后台运行，导致容器主进程立即退出）。
   • 正确示例：CMD ["nginx", "-g", "daemon off;"]（让 Nginx 前台运行成为主进程）。
3. 构建命令：

docker build -t my-image:1.0 . # -t 指定镜像名和标签，. 表示构建上下文（通常为当前目录）

构建上下文会打包目录内文件传递给 Docker 引擎，需避免包含无关文件（可通过 .dockerignore 过滤）。

二、CMD vs ENTRYPOINT：执行模式与区别

1. 执行模式（Exec vs Shell）

a. Exec 模式（推荐）

• 格式：CMD ["executable", "param1", "param2"]
• 特点：
  • 直接执行指定程序，不通过 Shell（如 /bin/sh）。
  • 环境变量需显式传递（如 ENTRYPOINT ["echo", "$HOME"] 不会解析 $HOME）。
  • 主进程为目标程序（PID 1），容器状态与程序生命周期一致。

b. Shell 模式

• 格式：CMD command param1 param2
• 特点：
  • 通过 /bin/sh -c 执行命令，主进程为 Shell（PID 1），目标程序为子进程（PID > 1）。
  • 自动解析环境变量（如 CMD echo $HOME 会输出 /root）。
  • 可能引发信号处理问题（如容器无法捕获程序的退出信号）。

2. CMD 指令

作用：定义容器默认执行的命令或参数，可被 docker run 命令覆盖。

语法形式

1. Exec 模式（推荐）：

CMD "python", "app.py" # 直接执行 Python 脚本

1. Shell 模式：

CMD python app.py # 等价于 CMD "sh", "-c", "python app.py"

1. 为 ENTRYPOINT 提供默认参数：

ENTRYPOINT "curl"

CMD "https://example.com" # 可通过 docker run my-image https://baidu.com 覆盖

覆盖规则

• 执行 docker run my-image custom-command 时，CMD 会被 custom-command 替换。
• 示例：

CMD "echo", "hello" # Dockerfile 中的默认命令

docker run my-image ls # 实际执行 ls（覆盖 CMD）

3. ENTRYPOINT 指令

作用：设置容器的固定入口命令，参数可通过 CMD 或 docker run 动态传递。

语法形式

1. Exec 模式（推荐）：

ENTRYPOINT "nginx", "-g", "daemon off;" # 前台运行 Nginx，主进程为 Nginx

1. Shell 模式：

ENTRYPOINT nginx -g "daemon off;" # 主进程为 sh，Nginx 为子进程

参数传递规则

• Exec 模式：docker run 的参数会追加到 ENTRYPOINT 之后。

ENTRYPOINT "curl", "-X"

CMD "GET"

docker run my-image POST https://example.com # 实际执行 curl -X POST https://example.com

• Shell 模式：docker run 的参数会被忽略，仅执行 ENTRYPOINT 定义的命令。

ENTRYPOINT curl https://example.com

docker run my-image https://baidu.com # 仍执行 curl https://example.com

强制覆盖 ENTRYPOINT

通过 --entrypoint 选项指定新的入口命令：

docker run --entrypoint ls my-image # 忽略 Dockerfile 中的 ENTRYPOINT，执行 ls

三、组合使用 CMD 和 ENTRYPOINT

四、最佳实践建议

1. 优先使用 Exec 模式：
   • 避免 Shell 模式的隐藏问题（如信号处理、性能损耗）。
   • 需要解析环境变量时，显式通过 sh -c 处理：undefinedENTRYPOINT "sh", "-c", "echo $HOME" # 正确解析 $HOME
2. 明确职责分工：
   • ENTRYPOINT：定义不可变的入口命令（如程序二进制文件）。
   • CMD：提供可覆盖的默认参数或备用命令。
3. 主进程唯一性：
   • 确保容器内只有一个主进程（如 Web 服务器、API 服务），避免多个阻塞进程导致容器异常退出。
4. 构建上下文优化：
   • 通过 .dockerignore 排除不必要的文件（如 node_modules、日志文件），减少构建时间和镜像体积。

*.log

node_modules/

1. 多阶段构建（减少镜像体积）：

FROM golang:1.20 AS builder

WORKDIR /app

COPY . .

RUN go build -o my-app

FROM alpine:3.17

COPY --from=builder /app/my-app /usr/bin/my-app

ENTRYPOINT "my-app"

五、常见问题与解决方案

问题 1：容器启动后立即退出

• 原因：主进程执行完毕或崩溃。
• 排查步骤：
  1. 使用 docker run -it my-image sh 进入容器，手动执行主进程命令，查看错误日志。
  2. 确保主进程为前台运行（如去掉 daemon 参数）。

问题 2：环境变量未生效

• 原因：使用 Exec 模式但未通过 Shell 解析。
• 解决方案：

ENTRYPOINT "sh", "-c", "echo $ENV_VAR && my-app" # 通过 Shell 解析环境变量

问题 3：无法通过 docker stop 优雅终止容器

• 原因：主进程为 Shell 模式下的子进程，无法接收 SIGTERM 信号。
• 解决方案：改用 Exec 模式，让主进程直接接收信号：

ENTRYPOINT "my-app" # 主进程为 my-app，可正确响应 docker stop

总结：选择策略

通过合理组合 CMD 和 ENTRYPOINT，可以灵活控制容器的启动行为，同时保持镜像的可复用性和可扩展性。更多实战案例可参考博客：Dockerfile使用技巧。