15.7.1 Dockerfile语法与指令详解

Dockerfile语法与指令详解#

Dockerfile 是镜像构建的声明式脚本，按“自上而下”顺序执行。核心目标是可复现、可维护、可审计。本节通过语法规则、指令详解、构建示例、排错与练习，建立可落地的 Dockerfile 编写习惯。

1. 原理草图：Dockerfile 到镜像的构建链路#

文章图片

2. 基本语法规则（含示例）#

  • 一行一条指令：INSTRUCTION arguments
  • 指令名不区分大小写，但推荐全大写
  • 使用 \ 续行
  • 注释以 # 开头

示例：

# /opt/demo/Dockerfile
FROM ubuntu:22.04
RUN apt-get update && \
    apt-get install -y curl && \
    rm -rf /var/lib/apt/lists/*

3. 常用指令详解与示例（含命令解释）#

3.1 FROM#

指定基础镜像，必须为第一条非注释指令
示例：

FROM alpine:3.19

3.2 LABEL#

添加元数据，方便检索
示例：

LABEL maintainer="ops@example.com" \
      app="demo" \
      version="1.0.0"

3.3 RUN#

构建阶段执行命令，产生新层
示例：

RUN apk add --no-cache bash curl

命令解释：
- apk add --no-cache：安装包且不保存索引，减小镜像

3.4 CMD 与 ENTRYPOINT#

  • CMD：默认启动命令，可被 docker run 覆盖
  • ENTRYPOINT：固定主进程，避免被覆盖
    示例：
ENTRYPOINT ["nginx","-g","daemon off;"]
CMD ["-c","/etc/nginx/nginx.conf"]

3.5 EXPOSE#

声明容器对外服务端口 

EXPOSE 80 443

3.6 ENV#

设置环境变量 

ENV APP_ENV=prod APP_PORT=8080

3.7 WORKDIR#

设置工作目录 

WORKDIR /app

3.8 COPY 与 ADD#

  • COPY：复制文件/目录
  • ADD：支持解压与远程 URL（谨慎） 
COPY ./src /app

3.9 VOLUME#

声明数据卷 

VOLUME ["/data"]

3.10 USER#

降权运行 

RUN adduser -D appuser
USER appuser

3.11 ARG#

构建时变量 

ARG BUILD_VERSION
ENV APP_VERSION=$BUILD_VERSION

3.12 HEALTHCHECK#

健康检查 

HEALTHCHECK --interval=30s --timeout=3s CMD curl -f http://localhost:8080/ || exit 1

4. 完整示例：构建一个 Nginx 静态站点镜像#

4.1 准备目录#

mkdir -p /opt/demo/html
cd /opt/demo
cat > html/index.html <<'EOF'
<h1>Hello Dockerfile</h1>
EOF

4.2 Dockerfile#

# /opt/demo/Dockerfile
FROM nginx:1.25-alpine
LABEL maintainer="ops@example.com" app="static-site"
WORKDIR /usr/share/nginx/html
COPY ./html/ /usr/share/nginx/html/
EXPOSE 80
HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost/ || exit 1

4.3 构建镜像#

cd /opt/demo
docker build -t demo-nginx:1.0 .

命令解释：
- docker build：执行构建
- -t：为镜像打标签

4.4 运行容器#

docker run -d --name demo-nginx -p 8080:80 demo-nginx:1.0

预期效果：
- 浏览器访问 http://localhost:8080 显示 Hello Dockerfile

5. 常见问题与排错#

5.1 COPY 失败：找不到文件#

排查步骤：

# 确认构建上下文
pwd
ls -l
# 重新构建并显示详细输出
docker build --no-cache -t demo-nginx:1.0 .

原因：构建上下文外的文件无法被 COPY

5.2 RUN 安装失败：源不可用#

排查步骤：

docker build -t demo-nginx:1.0 . --progress=plain

改用国内镜像或添加重试：

RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories

5.3 CMD/ENTRYPOINT 行为不符合预期#

验证启动命令：

docker inspect demo-nginx:1.0 | grep -A3 Cmd
docker run --rm demo-nginx:1.0 nginx -V

确保 JSON 数组格式正确，避免 shell 模式带来参数解析问题。

6. 练习题（含参考命令）#

1) 写一个 Dockerfile 安装 curl 并输出版本
- 参考：

FROM alpine:3.19
RUN apk add --no-cache curl
CMD ["curl","--version"]

2) 构建并运行，输出 curl 版本

docker build -t demo-curl:1.0 .
docker run --rm demo-curl:1.0

3) 使用 ARG 控制构建版本号

FROM alpine:3.19
ARG BUILD_VERSION
ENV APP_VERSION=$BUILD_VERSION
CMD ["sh","-c","echo $APP_VERSION"]

docker build -t demo-arg:1.0 --build-arg BUILD_VERSION=2024.01 .
docker run --rm demo-arg:1.0

通过以上示例，你可以掌握 Dockerfile 的核心语法、指令语义、常见排错方法与实战构建流程，为后续的镜像瘦身与多阶段构建打下基础。