Dockerfile optimization recommendation-Container Registry(ACR)-阿里云帮助中心

Container Registry Enterprise Edition automatically analyzes your Dockerfiles before each image build and reports potential issues in the build log. The analysis runs without any action on your part and does not affect the build outcome.

How it works

When you trigger an image build on a Container Registry Enterprise Edition instance, the Dockerfile optimization recommendation feature runs before the build starts. It checks your Dockerfile against two sets of rules:

Syntax rules — detect invalid instructions, unsupported parameters, and structural errors. For the full Dockerfile syntax reference, see Dockerfile reference.
Best practice rules — detect patterns that can cause unexpected build results, bloated image sizes, or security issues at container runtime.

Issues are reported at two severity levels:

Level	Meaning	Recommended action
Error	Syntax errors or parameters not supported by Container Registry. Can cause errors in image buildings.	Fix before building.
Warning	Potential issues that can produce unexpected build results or add unnecessary data to the image.	Review and fix as needed.

Analysis result format

Each issue appears on its own line in the build log using the following format:

[Error] <error message> at line <line number>: <instruction content>
[Warning] <warning message> at line <line number>: <instruction content>
[Error] [Rule <rule ID>] <error message> at line <line number>: <instruction content>
[Warning] [Rule <rule ID>] <warning message> at line <line number>: <instruction content>

Example 1: Syntax errors

The following Dockerfile contains multiple syntax errors:

# FROM uses an unsupported target architecture and omits the stage name.
FROM --platform=windows alpine as
# RUN uses an unsupported security mode.
RUN --security=insecure cat /proc/self/status | grep CapEff
# ADD has no destination path.
ADD https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz
# COPY does not support remote URLs — use ADD instead.
COPY https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz linux-0.01.tag.gz
# The source path does not exist in the build context.
COPY <Path that does not exist> /somedir/
# Unknown instruction name.
CPY /foo /bar

The build log reports:

[parse stage begin.]
[Error] Unsupported target architecture at line 2: windows.
[Error] Lack of stage name at line 2.
[Error] Unsupported security mode at line 4: insecure.
[Error] Lack of dest at line 6.
[Error] COPY does not support remote links. Please use the ADD instruction at line 8: https://mirrors.edge.kernel.org/pub/linux/kernel/Historic/linux-0.01.tar.gz.
[Error] Source path is not exist at line 10: <Path that does not exist>.
[Error] Unknown instruction at line 12: CPY.
[Warning] No tag specified at line 2: from ["--platform=windows"] "alpine" "as".
[parse successfully, takes 0s.]

Example 2: Best practice violations

The following Dockerfile violates several best practice rules:

# No image tag specified.
FROM alpine AS a
# Package cache not cleared after installation.
RUN apk add gcc
# No image tag specified. Stage name duplicates an existing stage.
from ubuntu as a
# Package cache not cleared. --no-install-recommends not used.
RUN apt-get install -y gcc

The build log reports:

[parse stage begin.]
[Warning] [Rule1003]When installing software with apt-get, it is recommended to include the --no-install-recommends parameter at line 8: RUN apt-get install -y gcc .
[Warning] No tag specified at line 2: FROM alpine AS a .
[Warning] No tag specified at line 6: from ubuntu as a .
[Warning] [Rule1001]Using a base image with a specific tag instead of the latest image.
[Error] Duplicate stage names with line 2: a at line 6: from ubuntu as a .
[Error] [Rule1014]Do not use duplicate stage names.
[parse successfully, takes 0s.]

Detection rules

Best practice rules

Rule	Level	Issue	Fix
R1001	Warning	Base image uses the `latest` tag, making builds non-deterministic.	Pin the base image to a specific tag.
R1002	Warning	`apt-get update`, `apt-get upgrade`, and `apt-get install` are in separate RUN instructions.	Combine all three into a single RUN instruction.
R1003	Warning	`apt-get install` is missing `--no-install-recommends`, causing unnecessary packages to be downloaded.	Add `--no-install-recommends` to the `apt-get install` instruction.
R1004	Warning	Package manager cache is not cleared after installation, adding unnecessary data to the image.	Clear the cache in the same RUN instruction: append `apt-get clean && rm -rf /var/lib/apt/lists/` to `apt-get`; append `rm -rf /var/cache/apk/` to `apk`; use `apk add --no-cache`; or append `yum clean` to `yum`.
R1005	Warning	Compilation commands such as `make` or `go build` run in the final image stage, adding build toolchains to the image.	Use a multi-stage build: compile in a separate stage and copy only the output binary to the final image.
R1006	Warning	WORKDIR uses a relative path. If a previous WORKDIR instruction changes, the relative path resolves to an unexpected location.	Use an absolute path in WORKDIR.
R1007	Error	Instructions such as `kill` or `shutdown` run during the build, which can cause security and stability issues.	Remove these instructions from the Dockerfile.
R1008	Warning	The image is built as the root user, which can introduce security risks at container runtime.	Switch to a non-root user before the final stage.
R1009	Warning	A `cd` instruction is used to change the working directory. `cd` has no effect at container runtime.	Replace `cd` with a WORKDIR instruction.
R1010	Error	`sudo` is used in the build. `sudo` is invalid during image builds.	Remove `sudo` from the Dockerfile.
R1011	Error	EXPOSE specifies an invalid port number or protocol. Valid port numbers are 0–65535; valid protocols are TCP and UDP.	Use valid EXPOSE parameters, such as `8080`, `8081/tcp`, or `8082/udp`.
R1012	Error	COPY copies multiple source files to a destination that is not a directory path.	Make sure the destination path ends with `/` or is an existing directory.
R1013	Error	COPY `--from` references a stage name that does not exist in the Dockerfile.	Make sure the stage name in `--from` matches a stage defined earlier in the Dockerfile.
R1014	Error	Multiple build stages share the same name in a multi-stage build.	Use a unique name for each stage.
R1015	Error	The first instruction in the Dockerfile is not FROM or ARG.	Start the Dockerfile with a FROM or ARG instruction.
R1016	Warning	Multiple CMD instructions are present. Only the last CMD takes effect.	Remove all CMD instructions except the one you intend to use.
R1017	Warning	Multiple ENTRYPOINT instructions are present. Only the last ENTRYPOINT takes effect.	Remove all ENTRYPOINT instructions except the one you intend to use.
R1018	Error	ADD copies multiple source files to a destination that is not a directory path.	Make sure the destination path ends with `/` or is an existing directory.
R1019	Warning	A compressed package is downloaded and extracted but the original archive is not deleted, adding unnecessary data to the image.	Combine the download, extraction, and deletion into a single RUN instruction.