1. Overview

1.概述

In this tutorial, we’ll learn how to add comments in a Dockerfile. We’ll also highlight a distinction between instructions that look like comments but aren’t.

在本教程中，我们将学习如何在Dockerfile中添加注释。我们还将强调区分那些看起来像注释但其实不是的指令。

2. Adding a Comment to a Dockerfile

2.在Docker文件中添加注释

We’ll use the following Dockerfile:

我们将使用下面的Docker文件。

FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial'

Let’s understand it quickly:

让我们快速了解它。

the first line states that we use the latest ubuntu image
the second line passes the echo command as a parameter of the shell

Let’s build our image:

让我们建立我们的图像。

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

Docker prints (amongst other lines we’re not listing) the two steps that run successfully. Let’s now see how we can add comments to our Dockerfile.

Docker打印了（在我们没有列出的其他行中）成功运行的两个步骤。现在让我们看看如何在我们的Docker文件中添加注释。

2.1. Creating a Single-Line Comment

2.1.创建一个单行注释

To comment a line, it must start with a #.

要评论一行，必须以#开头。。

Let’s see how to modify our Dockerfile to add some single-line comments:

让我们看看如何修改我们的Docker文件，添加一些单行注释。

# Declare parent image
FROM ubuntu:latest
# Print sentence
RUN echo 'This is a Baeldung tutorial'

Let’s build the modified image:

让我们来构建修改后的图像。

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

As expected, Docker successfully ran the two same steps as before.

正如预期的那样，Docker成功运行了与之前相同的两个步骤。

2.2. Multi-Line Comments

2.2 多行注释

There is no dedicated syntax in Docker to write multi-line comments. Thus, the only way to write a multi-line comment is to write multiple single-line comments in a row:

Docker中没有专门的语法来写多行注释。因此，写多行注释的唯一方法是在一排中写多个单行注释。

# This file is a demonstration
# For a Baeldung article
FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial'

Building the image still prints the same steps as before:

构建图像的步骤仍然和以前一样，都是打印。

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial'

3. Avoiding Pitfalls

3.避免陷阱

In this section, we’ll look at a couple of pitfalls we should be aware of. These are tricky lines of code that look like comments when they are not.

在这一节中，我们将看一下我们应该注意的几个陷阱。这些是棘手的代码行，看起来像注释，其实不是。

3.1. Comment or Command Argument?

3.1.评论或命令参数？

In Docker, it’s impossible to add a comment at the end of a line. Let’s see what happens if we try to add a sentence, formatted like a single-line comment, at the end of one of our instructions:

在Docker中，不可能在一行的末尾添加一个注释。让我们看看，如果我们试图在一条指令的结尾处添加一个格式类似于单行注释的句子，会发生什么。

FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial' # Print sentence

We’ll now build the image:

我们现在要建立图像。

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial' # Print sentence
#5 0.371 This is a Baeldung tutorial

We’ve included the sentence printed by the echo command to emphasize that the result’s indeed the same as what we had before. So what happened here? Did we actually add a comment at the end of the second line of our Dockerfile?

我们把echo命令所打印的句子包括在内，以强调结果确实与我们之前的情况相同。那么这里发生了什么？我们是否真的在Docker文件的第二行末尾添加了一个注释？

Actually, the # Print sentence is passed as additional arguments to the RUN command. In this case, the additional arguments happened to be ignored by this command. To convince ourselves, let’s now add a similar sentence at the end of the first line of our Dockerfile:

实际上，#打印句子是作为附加参数传递给RUN命令的。在这种情况下，这些附加参数恰好被这个命令忽略了。为了说服自己，现在让我们在Dockerfile的第一行末尾添加一个类似的句子。

FROM ubuntu:latest # Declare parent image
RUN echo 'This is a Baeldung tutorial'

Let’s try to build this image:

让我们试着建立这个形象。

$ docker build -t baeldungimage .
failed to solve with frontend dockerfile.v0: failed to create LLB definition: dockerfile parse error line 1: FROM requires either one or three arguments

Here, we got a very explicit error message which demonstrates our affirmation.

在这里，我们得到了一个非常明确的错误信息，证明了我们的肯定。

3.2. Parser Directives Are Not Comments

3.2.解析器指令不是注释

Parser directives tell the Dockerfile parser how to handle the content of the file. Similarly to comments, parser directives start with a #.

解析器指令告诉Dockerfile解析器如何处理文件的内容。与注释类似，解析器指令以#开头。

Additionally, we should note that parser directives must be at the top of the Dockerfile. For instance, we’ll use the escape parser directive in our file. This directive changes the escape character used in the file:

此外，我们应该注意，解析器指令必须在Docker文件的顶部。例如，我们将在文件中使用escape解析器指令。这个指令可以改变文件中使用的转义字符。

# escape=`
FROM ubuntu:latest
RUN echo 'This is a Baeldung tutorial&' `
  && echo 'Print more stuff'

Here, we’ve added another echo instruction to the RUN command. For more readability, we’ve put this instruction on a new line. The default line separator is \. However, since we used the parser directive, we need to use ` instead. Let’s now build our image and see what happens:

在这里，我们在RUN命令中加入了另一条echo指令。为了提高可读性，我们把这条指令放在一个新的行上。默认的行分隔符是。然而，由于我们使用了解析器指令，我们需要使用`来代替。现在让我们建立我们的图像，看看会发生什么。

$ docker build -t baeldungimage .
#4 [1/2] FROM docker.io/library/ubuntu:latest
#5 [2/2] RUN echo 'This is a Baeldung tutorial&' && echo 'Print more stuff'
#5 0.334 This is a Baeldung tutorial&
#5 0.334 Print more stuff

The two sentences have been printed as expected.

这两个句子已按预期打印出来了。

4. Conclusion

4.总结

In this article, we’ve seen how to write comments in a Dockerfile. We’ve also learned that there’s a set of instructions called parser directives, that look very similar to comments but have a real impact on our file.

在这篇文章中，我们已经看到了如何在Docker文件中写注释。我们还了解到，有一组指令被称为解析器指令，它们看起来与注释非常相似，但对我们的文件有实际影响。

As always, the code can be found over on GitHub.

一如既往，代码可以在GitHub上找到over。