docker build参数有哪些关键选项？

基本语法

docker build [OPTIONS] PATH | URL | -

• PATH：本地构建上下文的路径，通常是包含 Dockerfile 的目录。docker build 会递归地遍历这个目录下的所有文件和子目录，并将它们发送给 Docker 守护进程。
• URL：一个 Git 仓库的 URL，Docker 会自动克隆该仓库并尝试在根目录或指定分支/标签下寻找 Dockerfile。
• 从标准输入读取 Dockerfile 和构建上下文，这在 CI/CD 流水线中非常有用，例如将 Dockerfile 通过管道传递给 docker build。

核心参数详解

下面我们分类介绍最重要的参数。

指定 Dockerfile 和构建上下文

这是最常用且最容易混淆的参数。

-f, --file string

• 作用：指定 Dockerfile 的路径，默认情况下，Docker 会在构建上下文的根目录下寻找名为 Dockerfile 的文件。

• 场景：

  • 你的 Dockerfile 不在构建上下文的根目录。
  • 你的 Dockerfile 不叫 Dockerfile（Dockerfile.dev）。

• 示例：

  
  （图片来源网络，侵删）

    # 在 /home/user/my_project 目录下构建，但使用 /home/user/my_project/docker/Dockerfile.prod 文件
    docker build -f /home/user/my_project/docker/Dockerfile.prod /home/user/my_project
    # 使用当前目录下的 Dockerfile.dev 文件
    docker build -f Dockerfile.dev .

--build-context name=PATH

• 作用：向构建上下文中添加额外的文件或目录，这允许你在 Dockerfile 中通过 name 引用这些外部资源，而无需将它们复制到主构建上下文中。

• 场景：

  • 构建需要一些敏感文件（如密钥、证书），但你不希望它们被包含在最终的镜像层中。
  • 共享一些通用的构建脚本或依赖文件给多个 Dockerfile 使用。

• 示例：

    # 假设有一个私有的 Go 模块，存放在 /path/to/private/module
    # 将其作为 "mymodule" 上下文传递给 Docker
    docker build --build-context mymodule=/path/to/private/module -f Dockerfile .
    # 在 Dockerfile 中使用
    # FROM golang as builder
    # COPY --from=mymodule /src /app/src

--no-cache

• 作用：禁用构建缓存，默认情况下，Docker 会缓存镜像的中间层以加速后续构建，此参数会强制 Docker 重新执行所有指令。
• 场景：
  • 确保每次构建都是完全从头开始,这对于获取最新的依赖项非常有用。
  • 调试缓存导致的问题。
• 示例：

    docker build --no-cache -t myapp:latest .

控制镜像标签和输出

-t, --tag string

• 作用：为构建的镜像指定一个或多个标签，格式为 name:tag 或 name@digest，如果不指定，镜像会得到一个 <none> 的标签。

  
  （图片来源网络，侵删）

• 场景：这是构建镜像后最重要的操作，为镜像打上易于识别的标签。

• 示例：

    # 打一个标签 myapp:latest
    docker build -t myapp:latest .
    # 打多个标签
    docker build -t myapp:latest -t myapp:v1.0.0 .
    # 指定仓库地址
    docker build -t my-docker-hub-username/myapp:v1.0.0 .

-o, --output stringArray

• 作用：将构建的镜像输出到指定的位置，而不是推送到 Docker 镜像仓库，它支持多种格式。

• 场景：

  • 将镜像导出为 .tar 文件。
  • 将镜像推送到本地 OCI 兼容的镜像仓库。
  • 在 CI/CD 流水线中，将镜像作为产物保存。

• 示例：

    # 导出到一个 tar 文件
    docker build -o type=tar,dest=/path/to/myapp.tar .
    # 导出到一个本地目录（会生成一个 manifest.json 和多个 layer 文件）
    docker build -o type=local,dest=/path/to/output/dir .
    # 导出到一个本地 OCI v1 仓库
    docker build -o type=oci,dest=/path/to/oci-repo .

运行时与网络控制

--platform string

• 作用：指定目标平台的架构和操作系统，这对于构建跨平台镜像（如 ARM、AMD64）至关重要。

• 场景：

  • 在 macOS (Apple Silicon) 上构建适用于 Linux x86_64 的镜像。
  • 在 CI/CD 中为不同架构构建镜像。

• 示例：

    # 构建针对 Linux AMD64 架构的镜像
    docker build --platform linux/amd64 -t myapp:linux-amd64 .
    # 构建针对 Linux ARM64 架构的镜像
    docker build --platform linux/arm64 -t myapp:linux-arm64 .
    # Dockerfile 中有 `--platform` 指令，可以构建多平台镜像
    docker buildx build --platform linux/amd64,linux/arm64 -t myapp:multi-platform .

--network string

• 作用：在构建期间设置容器的网络模式。

• 场景：

  • default：使用默认的网络。
  • none：禁用网络，RUN 指令将无法访问外部网络，适合构建离线镜像。
  • host：使用主机的网络栈，RUN 指令可以直接访问主机网络。

• 示例：

    # 构建时禁用网络，防止下载外部依赖
    docker build --network none -t myapp:offline .
    # 构建时使用主机网络，可以直接访问主机上的服务
    docker build --network host -t myapp:with-host-net .

安全与秘密管理

--secret id=mysecret,src=/local/secret/file

• 作用：在构建过程中将敏感数据（如密码、API 密钥）传递给容器，但这些数据不会出现在镜像的最终层中，从而提高了安全性。

• 场景：在 Dockerfile 中需要访问秘密信息，但又不希望它们被硬编码或泄露到镜像中。

• 要求：Dockerfile 中的指令必须支持 --mount=type=secret。

• 示例：

    # 假设有一个 AWS 密钥文件 ~/.aws/credentials
    docker build --secret id=awscreds,src=~/.aws/credentials -t myapp:with-secrets .
    # 在 Dockerfile 中使用
    # FROM alpine
    # RUN --mount=type=secret,id=awscreds,target=/root/.aws/credentials \
    #     apk add --no-cache curl && \
    #     curl -H "Authorization: $(cat /root/.aws/credentials)" https://api.example.com

--ssh default

• 作用：将 SSH 代理套接字传递给构建容器，允许你在构建过程中（RUN 指令里）使用 git clone 或 ssh 访问私有 Git 仓库。

• 场景：从私有 Git 仓库拉取代码进行构建。

• 要求：Dockerfile 中的指令必须支持 --mount=type=ssh。

• 示例：

    # 确保 SSH 代理正在运行，并且设置了 SSH_AUTH_SOCK 环境变量
    docker build --ssh default -t myapp:git-ssh .
    # 在 Dockerfile 中使用
    # FROM alpine
    # RUN apk add --no-cache git openssh-client && \
    #     mkdir -p ~/.ssh && \
    #     chmod 0700 ~/.ssh && \
    #     --mount=type=ssh \
    #     git clone git@github.com:my-private-org/private-repo.git

高级与多阶段构建

--target string

• 作用：构建一个多阶段构建（Multi-stage build）的特定阶段，而不是最后一个阶段。

• 场景：

  • 在调试时,只想构建到某个中间阶段（如 builder 阶段）。
  • 为不同目的构建不同版本的镜像（如一个包含构建工具的调试镜像，和一个精简的生产镜像）。

• 示例：

    # Dockerfile 中有多个 FROM 指令，
    # FROM golang as builder
    # ...
    # FROM alpine as final
    # ...
    # 只构建到 "builder" 阶段
    docker build --target builder -t myapp:builder .
    # 构建最终的 "final" 阶段（默认行为）
    docker build --target final -t myapp:final .

--progress string

• 作用：控制构建进度的输出格式。
• 场景：
  • auto (默认)：根据终端是否为 TTY 自动选择。
  • plain：纯文本输出，适合重定向到文件或管道。
  • tty：与 auto 在 TTY 中类似，显示更详细的彩色输出。
• 示例：

    # 以纯文本格式输出构建日志，方便保存到日志文件
    docker build --progress=plain -t myapp:latest . > build.log

实践示例

场景：在一个 CI/CD 流水线中，为 linux/amd64 和 linux/arm64 架构构建一个多阶段镜像，并缓存依赖，最后将镜像推送到镜像仓库。

# 假设 Dockerfile 有一个名为 "builder" 的阶段和一个最终的 "production" 阶段
# 我们想利用缓存，但确保代码是最新的
# 1. 构建 amd64 版本，使用缓存，但确保从 git 拉取最新代码
docker build \
  --platform linux/amd64 \
  --target builder \
  -t myapp:builder-amd64 \
  -t myapp:latest-amd64 \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  .
# 2. 构建 arm64 版本
docker build \
  --platform linux/arm64 \
  --target builder \
  -t myapp:builder-arm64 \
  -t myapp:latest-arm64 \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  .
# 3. (可选) 使用 buildx 构建并推送多平台镜像
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --target production \
  -t myusername/myapp:latest \
  -t myusername/myapp:v1.0.0 \
  --push \
  .

掌握这些参数能让你更灵活、更高效、更安全地使用 docker build 命令，对于更复杂的需求（如多平台、多节点构建），还需要学习 docker buildx。