【避坑指南】Docker build 报错 “requires exactly 1 argument”？忘了这个点吗？

摘要：使用 Docker 构建镜像时，你是否遇到过 docker build -t myimage . 明明看起来正确，却仍然提示 “requires exactly 1 argument” 的错误？本文通过一个真实案例，从报错现场开始，逐步还原排查思路，最终给出完整的解决方案，并深入剖析 Docker 构建上下文的原理。无论是新手踩坑还是老手偶然疏忽，这篇文章都能帮你快速定位问题，避开常见的参数陷阱。

---

引言

某个周五下午，你正打算快速构建一个新服务的镜像去测试环境验证，随手敲下 docker build -t my-service，回车——等等，怎么报错了？一行红字告诉你 “requires exactly 1 argument”。明明已经给了镜像名，为什么还说缺参数？这种场景相信不少人都亲身经历过。别急，问题的根源其实出在一个小小的.上。

这次，我们就来把这个“参数缺失”的坑彻底填平，让你从此告别这种低级错误。

---

环境说明

项目	版本/配置
操作系统	macOS 14 / Ubuntu 22.04
Docker 版本	24.0.7 及以上
构建模式	Docker Buildx（默认）
项目目录	含有 Dockerfile 的根目录

注：本文以 Docker CE 24.x 为例，但原理适用于所有支持 BuildKit/Buildx 的 Docker 版本。

---

错误现场

当你执行一条看起来无比正常的 build 命令时：

$ docker build -t my-service

Docker 会立刻抛出一个错误：

"docker build" requires exactly 1 argument.
See 'docker build --help'.

Usage:  docker build [OPTIONS] PATH | URL | -
...

这个错误告诉我们：docker build 命令除了选项之外，还必须跟随恰好一个参数，即构建上下文（PATH、URL 或 -）。而我们只给出了 -t 选项，并没有提供这个必须的上下文路径。

---

排查思路

1. 直觉反应：是不是 -t 后面忘了加镜像名？

• 做了什么：检查命令，补全镜像名，输入 docker build -t my-service:latest。
• 结果：依然报错 "docker build" requires exactly 1 argument.
• 为什么不行：错误并不是因为缺少镜像名，而是命令最后没有指定构建上下文路径。

2. 回到最熟悉的写法：加上当前目录的 .

• 做了什么：在命令末尾加上点号，变成 docker build -t my-service .
• 结果：成功开始构建，一切都正常了。
• 发现：原来完整的 docker build 语法中，构建上下文路径是位置参数，缺了它 Docker 就会抱怨。

3. 扩展思考：如果 Dockerfile 不在当前目录呢？

• 尝试：使用 -f 指定 Dockerfile 路径时，是否还需要上下文？
• 测试：执行 docker build -t my-service -f docker/Dockerfile.dev .
• 结果：仍然需要末尾的 .，哪怕我们用 -f 明确指定了 Dockerfile 的位置。
• 结论：-f 只负责指定 Dockerfile 文件路径，构建上下文的参数依然是必须的，且不能省略。

4. 新版本 Docker 使用 buildx 的情况

• 尝试：在某些新版本 Docker 中，docker build 默认会调用 docker buildx build。
• 执行：docker buildx build -t my-service .
• 结果：同样需要末尾的路径参数。
• 总结：无论是传统的 docker build 还是 buildx，语法中对上下文路径的要求是一致的。

---

终极解决方案

下面给出不同场景下 docker build 的正确写法，确保一步到位。

场景1：标准构建（Dockerfile 在当前目录）

# 注意末尾的点号，代表将当前目录作为构建上下文
docker build -t my-service:latest .

场景2：Dockerfile 在其他路径

# 使用 -f 指定 Dockerfile 的路径，末尾仍需指定构建上下文（通常使用当前目录 . ）
docker build -t my-service -f docker/Dockerfile.dev .

场景3：使用 Docker Buildx 进行跨平台构建

# Buildx 的语法与 docker build 完全兼容，同样需要上下文路径
docker buildx build -t my-service:latest --platform linux/amd64,linux/arm64 .

场景4：通过 URL 或标准输入提供上下文

# 从远程 Git 仓库构建（上下文为仓库地址）
docker build -t my-service https://github.com/user/repo.git#main:subdir

# 从标准输入读取 Dockerfile 和上下文（用 - 表示）
docker build -t my-service - < my-dockerfile.tar

关键点：无论哪种变体，docker build 命令的最后一项都是构建上下文，它是一个位置参数，不能省略。

如果仍然遇到 “requires exactly 1 argument” 的错误，请回头检查命令末尾是否缺少了一个点（.）或其它有效的上下文路径。

---

原理浅析

为什么 Docker 非要我们指定一个“构建上下文”呢？我们可以把构建上下文想象成一个 “文件传送带”。

当你执行 docker build . 时，Docker 客户端会把 . 所代表的整个目录（包括子目录）打包成一个 tar 文件，发送给 Docker 守护进程。守护进程拿到这个包之后，才能根据 Dockerfile 中的 COPY 或 ADD 指令，从里面提取所需的文件。

因此，构建上下文是整个构建动作的起点：

• 如果没有指定上下文，守护进程根本不知道去哪里找要复制的文件。
• 即使 Dockerfile 中没有任何 COPY 指令，Docker 架构上仍然需要一个上下文（哪怕是一个空目录），因为守护进程需要从该上下文中读取 Dockerfile（默认情况）。

至于 -f 参数，它只是告诉客户端 “不去上下文根目录找 Dockerfile，而是去这个指定的文件路径读取”。但上下文本身依然需要，因为 -f 指向的 Dockerfile 可以放在任意位置，甚至可以在上下文之外（这种情况下该 Dockerfile 不能引用需从上下文复制的文件，否则会失败）。

所以，位置参数不存在默认值（例如默认用当前目录），Docker 必须要求用户显式地指出上下文，这是设计上的安全考量，也是避免歧义的必要措施。

---

总结与避坑

• 核心要点：docker build 命令的末尾始终需要提供一个构建上下文路径（常用 . 表示当前目录），它是必选的位置参数，不是 -t 的子项。
• 记忆口诀：docker build -t 镜像名 上下文，少任何一部分都不行。
• 扩展建议：
  1. 即使 Dockerfile 在别处，上下文路径仍然必须提供，且通常使用当前目录 .。
  2. 如果你不需要复制任何文件，可以创建一个空临时目录，然后 docker build -t my-image -f /path/to/Dockerfile /path/to/empty-dir，减少上传的数据量。
  3. 使用 .dockerignore 文件排除不希望发送到上下文的大文件或敏感目录（如 node_modules、.git），可显著加快构建速度。
• 常见注意事项：
  • 切勿在根目录 / 下执行构建，否则上下文会包含整个文件系统，导致 Docker 守护进程卡死或磁盘爆满。
  • 当使用 Buildx 构建时，语法和传统 docker build 完全一致，上下文参数的要求不变。

明白了这些，下次再看到 “requires exactly 1 argument” 时，你会心一笑，默默地在命令后面补上一个.。