docker build
是用于从 Dockerfile 构建 Docker 镜像的核心命令,通过读取 Dockerfile 中的指令,逐步构建出可运行的镜像。以下是其详细用法、参数说明及示例:
一、基本语法
bash
docker build [OPTIONS] PATH | URL | -
PATH
:Dockerfile 所在的本地目录路径(最常用);URL
:远程 Git 仓库地址(如https://github.com/example/project.git
);-
:从标准输入(stdin
)读取 Dockerfile 内容(较少用)。
二、常用参数(OPTIONS)
参数 | 作用说明 |
---|---|
-t, --tag |
为镜像指定名称和标签(格式:名称:标签 ,标签默认 latest ) |
-f, --file |
指定非默认名称的 Dockerfile(默认找当前目录的 Dockerfile 文件) |
--build-arg |
传递构建时变量(配合 Dockerfile 中的 ARG 指令使用) |
--no-cache |
构建时不使用缓存(强制重新执行所有步骤,解决缓存导致的依赖更新问题) |
--pull |
总是尝试拉取基础镜像的最新版本(避免使用本地旧版本基础镜像) |
-q, --quiet |
静默模式,只输出最终的镜像 ID,不显示构建过程 |
三、示例场景
1. 基础用法:从当前目录构建镜像
假设当前目录有 Dockerfile
,构建并命名为 myapp:v1
:
bash
# 格式:docker build -t 镜像名:标签 目录路径(. 表示当前目录)
docker build -t myapp:v1 .
2. 指定非默认名称的 Dockerfile
若 Dockerfile 名为 Dockerfile.prod
(非默认 Dockerfile
):
bash
# -f 指定 Dockerfile 路径
docker build -t myapp:prod -f Dockerfile.prod .
3. 传递构建时变量(--build-arg)
配合 Dockerfile 中的 ARG
指令使用,动态传入参数(如版本号):
Dockerfile 中定义 ARG
:
dockerfile
ARG APP_VERSION=1.0 # 定义变量,默认值 1.0
FROM openjdk:8-jdk-alpine
COPY app-${APP_VERSION}.jar app.jar # 使用变量
构建时传递变量:
bash
# --build-arg 覆盖默认的 APP_VERSION
docker build -t myapp:v2 --build-arg APP_VERSION=2.0 .
4. 强制不使用缓存(--no-cache)
当 Dockerfile 或依赖文件更新后,缓存可能导致构建结果不符合预期,需强制重新构建:
bash
docker build -t myapp:v3 --no-cache .
5. 从远程 Git 仓库构建
直接从 GitHub/GitLab 仓库构建(Docker 会自动克隆仓库并找根目录的 Dockerfile):
bash
# 从 GitHub 仓库构建
docker build -t github-app:latest https://github.com/example/springboot-demo.git
6. 静默模式构建(-q)
只输出最终的镜像 ID,适合脚本中获取镜像标识:
bash
# 构建并获取镜像 ID
IMAGE_ID=$(docker build -q -t myapp:v4 .)
echo "构建完成,镜像 ID:$IMAGE_ID"
四、构建上下文(Context)
docker build
后面的 PATH
(如 .
)称为构建上下文,表示 Docker 引擎可访问的文件范围:
-
构建时,Docker 会将上下文目录下的所有文件发送到 Docker 引擎(因此上下文目录不应包含无关文件,避免传输缓慢);
-
建议:在上下文目录中创建
.dockerignore
文件,排除不需要的文件(如node_modules
、.git
),示例:bash# .dockerignore 内容 node_modules/ .git/ *.log
五、常见错误及解决
-
unauthorized: authentication required
需登录 Docker 仓库(如 Docker Hub):
docker login
-
no such file or directory
检查 Dockerfile 中的
COPY/ADD
路径是否正确,确保文件在构建上下文内。 -
缓存导致依赖未更新
使用
--no-cache
强制重新构建,或修改 Dockerfile 中对应步骤的指令(如添加注释)使缓存失效。
docker build
是构建镜像的核心命令,常用场景:
- 基础构建:
docker build -t 名称:标签 .
- 定制 Dockerfile 路径:
-f
参数 - 动态传参:
--build-arg
- 清除缓存:
--no-cache