一、Dockerfile 基础概念

（一）本质与作用

Dockerfile 是用于定义 Docker 镜像构建流程的文本文件，包含一系列指令和说明，指导 Docker 引擎生成定制化镜像。其核心价值在于：

• 标准化构建：通过文本文件定义镜像构建流程，确保环境一致性
• 可复用性：一次编写可重复构建相同镜像
• 版本可控：可通过版本控制管理 Dockerfile 迭代

（二）核心特性

1. 分层构建：每条指令创建一个镜像层，支持增量更新
2. 声明式语法：以指令形式声明镜像所需状态，而非过程式脚本
3. 上下文机制：构建时需指定上下文路径，包含所需文件

二、镜像构建实战流程

（一）案例：定制 Nginx 镜像

1. 创建 Dockerfile

# 基于官方 Nginx 镜像
FROM nginx
# 在容器内创建自定义首页
RUN echo '这是一个本地构建的 Nginx 镜像' > /usr/share/nginx/html/index.html

2. 执行构建命令

# -t 指定镜像名称:标签，. 表示上下文路径
docker build -t nginx:v3 .

3. 构建过程解析

Sending build context to Docker daemon  2.048kB
Step 1/2 : FROM nginx
 ---> 540a289bab6c
Step 2/2 : RUN echo '这是一个本地构建的 Nginx 镜像' > /usr/share/nginx/html/index.html
 ---> Running in b776f6943ac5
Removing intermediate container b776f6943ac5
 ---> 4ac05b52e7fe
Successfully built 4ac05b52e7fe
Successfully tagged nginx:v3

三、上下文路径深度解析

（一）概念与作用

• 定义：构建镜像时指定的文件路径，Docker 会将该路径下所有内容打包发送给引擎
• 作用：提供构建过程中所需的文件（如复制到镜像的文件）
• 注意：上下文路径包含的文件越多，打包传输时间越长，应仅包含必要文件

（二）典型应用场景

# 项目结构
project/
├── Dockerfile
├── app.py
├── requirements.txt
└── static/

# 构建时指定项目根目录为上下文
docker build -t myapp:latest ./project

四、核心指令详解

（一）基础构建指令

（二）运行时配置指令

（三）环境与元数据指令

五、指令深度对比与实践

（一）RUN vs CMD vs ENTRYPOINT

1. 执行时机

• RUN：构建时执行，用于安装依赖等构建操作
• CMD：运行时执行，作为容器默认命令
• ENTRYPOINT：运行时执行，作为容器入口点，不可覆盖

2. 典型组合场景

FROM ubuntu
# 构建时安装工具
RUN apt-get update && apt-get install -y curl
# 设置入口点为 curl
ENTRYPOINT ["curl"]
# 为入口点提供默认参数
CMD ["https://runoob.com"]

• 执行 docker run myimage 时，实际运行 curl https://runoob.com
• 执行 docker run myimage https://baidu.com 时，运行 curl https://baidu.com

（二）COPY vs ADD

1. 功能对比

2. 推荐用法

# 复制本地文件
COPY requirements.txt .
# 下载远程文件（推荐用 RUN）
RUN wget -O data.tar.gz https://example.com/data.tar.gz
# 解压压缩包（仅在必要时用 ADD）
ADD data.tar.gz /data/

六、最佳实践与优化策略

（一）镜像大小优化

1. 使用轻量级基础镜像：

# 替换为 alpine 基础镜像（仅 5MB）
FROM alpine:3.14

2. 合并多层指令：

# 优化前（3层）
RUN apt-get update
RUN apt-get install -y python3
RUN pip3 install flask

# 优化后（1层）
RUN apt-get update && apt-get install -y python3 && pip3 install flask

3. 清理临时文件：

RUN apt-get update && apt-get install -y \
    python3 \
  && pip3 install flask \
  && rm -rf /var/lib/apt/lists/*  # 清理缓存

（二）安全性增强

1. 使用非 root 用户：

# 创建非 root 用户
RUN useradd -m appuser
# 切换为 appuser 用户
USER appuser

2. 最小化权限：

# 仅暴露必要端口
EXPOSE 80
# 禁止容器内不必要的服务
CMD ["nginx", "-g", "daemon off;"]

（三）构建效率优化

1. 利用构建缓存：

# 先复制依赖文件，利用缓存
COPY requirements.txt .
RUN pip install -r requirements.txt
# 再复制代码（代码变化时仅重建此层）
COPY . .

2. 指定构建参数：

ARG VERSION=1.0
LABEL app.version=$VERSION

# 构建时指定参数
docker build --build-arg VERSION=1.1 -t myapp:1.1 .

七、复杂场景实战案例

（一）Python Web 应用镜像

# 基础镜像使用 Python 官方镜像
FROM python:3.9-slim

# 设置工作目录
WORKDIR /app

# 复制依赖文件（优先利用缓存）
COPY requirements.txt .
# 安装依赖
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 5000

# 设置环境变量
ENV FLASK_APP=app.py
ENV FLASK_ENV=production

# 定义容器启动命令
CMD ["gunicorn", "-b", "0.0.0.0:5000", "app:app"]

（二）多阶段构建（Go 应用）

# 构建阶段
FROM golang:1.17 as builder

WORKDIR /app
COPY . .
# 编译二进制文件（-ldflags 优化部署体积）
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o app .

# 发布阶段（使用轻量级 alpine 镜像）
FROM alpine:3.14

WORKDIR /app
# 仅复制编译好的二进制文件
COPY --from=builder /app/app .

# 暴露端口
EXPOSE 8080

# 启动应用
ENTRYPOINT ["./app"]

八、常见问题与解决方案

（一）构建失败排查

1. 网络问题

failed to solve: unable to get registry endpoint: Get "https://registry-1.docker.io/v2/": dial tcp: lookup ...

• 解决：配置国内镜像源（如中科大镜像）

// /etc/docker/daemon.json
{
  "registry-mirrors": ["https://docker.mirrors.ustc.edu.cn"]
}

2. 权限问题

ERROR: failed to compute cache key: "/app" not found: not found

• 解决：确保上下文路径包含所需文件

# 错误：在 project 外执行，缺少 app 目录
docker build -t myapp ./project

# 正确：在 project 目录内执行
cd project && docker build -t myapp .

（二）运行时命令覆盖问题

1. 现象

docker run myimage sh -c "echo hello"
# 预期：输出 hello，实际：执行了 Dockerfile 中的 CMD 命令

• 解决：明确覆盖 CMD 或 ENTRYPOINT

# 覆盖 CMD
docker run myimage sh -c "echo hello"

# 覆盖 ENTRYPOINT
docker run --entrypoint sh myimage -c "echo hello"

通过掌握 Dockerfile 的核心指令与最佳实践，能够构建出高效、安全、可维护的容器镜像。在实际项目中，建议结合 CI/CD 流程自动构建镜像，并利用镜像仓库进行版本管理，确保开发、测试、生产环境的一致性与可追溯性。