docker build

从 Dockerfile 和上下文构建镜像。

使用方法

docker build [OPTIONS] PATH | URL | -

描述

docker build 命令从 Dockerfile 和构建上下文构建 Docker 镜像。构建上下文可以是本地路径、Git 仓库 URL 或标准输入（-）。

提示

构建上下文是 Docker 可以访问的文件和目录集合。Dockerfile 中的 COPY 和 ADD 指令只能访问构建上下文中的文件。

基本示例

# 从当前目录构建
docker build .

# 指定 Dockerfile 路径
docker build -f Dockerfile.dev .

# 指定标签
docker build -t myapp:latest .

# 指定多个标签
docker build -t myapp:latest -t myapp:1.0 .

# 从 Git 仓库构建
docker build https://github.com/user/repo.git

# 从标准输入构建
docker build - < Dockerfile

选项说明

基础选项

参数	简写	类型	默认值	描述
--tag	-t	list	-	为镜像指定名称和标签（格式：name:tag）
--file	-f	string	Dockerfile	指定 Dockerfile 路径
--target	-	string	-	设置构建目标（多阶段构建）
--platform	-	string	-	设置目标平台（例如：linux/amd64, linux/arm64）

构建控制

参数	简写	类型	默认值	描述
--no-cache	-	bool	false	不使用缓存构建
--pull	-	bool	false	总是尝试拉取基础镜像的新版本
--build-arg	-	list	-	设置构建参数（格式：KEY=value）
--progress	-	string	auto	设置进度输出类型：auto, plain, tty
--quiet	-q	bool	false	抑制构建输出，只显示镜像 ID
--rm	-	bool	true	构建成功后删除中间容器

网络和缓存

参数	简写	类型	默认值	描述
--network	-	string	default	设置构建时的网络模式
--cache-from	-	list	-	指定用作缓存源的镜像
--cache-to	-	list	-	将缓存导出到指定位置

安全选项

参数	简写	类型	默认值	描述
--secret	-	list	-	传递密钥到构建（BuildKit）
--ssh	-	list	-	传递 SSH socket 到构建（BuildKit）

其他选项

参数	简写	类型	默认值	描述
--label	-	list	-	设置镜像元数据标签
--output	-o	string	-	输出目录或 tar 文件（BuildKit）
--load	-	bool	false	构建后加载到 Docker（BuildKit）
--iidfile	-	string	-	将镜像 ID 写入文件

常用组合示例

基本构建

# 构建并标记镜像
docker build -t myapp:latest .

# 构建多个标签
docker build -t myapp:latest -t myapp:1.0.0 .

使用构建参数

# 传递构建参数
docker build \
  --build-arg NODE_ENV=production \
  --build-arg VERSION=1.0.0 \
  -t myapp:latest .

在 Dockerfile 中使用：

ARG NODE_ENV=development
ARG VERSION

ENV NODE_ENV=$NODE_ENV
ENV VERSION=$VERSION

多阶段构建

# 构建特定阶段
docker build --target builder -t myapp:builder .

# 构建最终阶段
docker build --target production -t myapp:latest .

不使用缓存

# 完全重新构建
docker build --no-cache -t myapp:latest .

跨平台构建

# 构建 ARM64 镜像（需要 buildx）
docker buildx build --platform linux/arm64 -t myapp:arm64 .

使用 BuildKit 高级特性

# 使用密钥（BuildKit）
docker build --secret id=mysecret,src=./secret.txt -t myapp:latest .

# 使用 SSH（BuildKit）
docker build --ssh default -t myapp:latest .

Dockerfile 最佳实践

1. 使用 .dockerignore

创建 .dockerignore 文件排除不需要的文件：

node_modules
.git
.env
*.log
dist

2. 多阶段构建

# 构建阶段
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# 生产阶段
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

3. 层缓存优化

# 好的做法：先复制依赖文件
COPY package*.json ./
RUN npm install

# 然后复制源代码
COPY . .
RUN npm run build

构建上下文

构建上下文是 Docker 可以访问的文件集合。默认情况下，Docker 会将整个上下文发送到 Docker daemon。

注意

构建上下文应该尽可能小，只包含构建所需的文件。使用 .dockerignore 排除不必要的文件。

相关命令

• docker images - 列出镜像
• docker tag - 标记镜像
• docker push - 推送镜像
• docker run - 运行容器

BSFC Tech Pro Tip

在生产环境中，建议使用多阶段构建来减小最终镜像大小，并使用 --target 选项构建特定阶段。同时，使用 .dockerignore 排除不必要的文件可以显著加快构建速度。