From 02e53c4597f2b596541c09d2d213258585d63fb2 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Sun, 16 Aug 2026 05:45:55 +0500
Subject: [PATCH] docs: note ARG defaults override automatic TARGETPLATFORM

Signed-off-by: Dean Chen <862469039@qq.com>
---
 content/manuals/build/building/multi-platform.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/content/manuals/build/building/multi-platform.md b/content/manuals/build/building/multi-platform.md
index 8ffae449a5db..0aede586c6a8 100644
--- a/content/manuals/build/building/multi-platform.md
+++ b/content/manuals/build/building/multi-platform.md
@@ -226,6 +226,18 @@ FROM alpine
 COPY --from=build /log /log
 ```
 
+Declare these automatic arguments with no default. A default such as
+`ARG TARGETPLATFORM=linux/amd64` is treated as a user-set value, so it wins
+over `--platform`. If you need a fallback for builders that do not set the
+automatic arguments, apply it later:
+
+```dockerfile
+ARG TARGETPLATFORM
+ENV TARGETPLATFORM=${TARGETPLATFORM:-linux/amd64}
+```
+
+The same applies to `TARGETOS`, `TARGETARCH`, and `TARGETVARIANT`.
+
 ## Examples
 
 Here are some examples of multi-platform builds: