Bạn truyền --build-arg APP_MODE=release nhưng ứng dụng khi chạy vẫn không đọc được biến môi trường mong muốn. Một build argument không tự trở thành biến runtime. Cần nhìn vào Dockerfile để biết giá trị ấy đã được dùng và lưu vào đâu.
Bài đọc Docker Build variables, Dockerfile reference và tài liệu scratch ngày 04/11/2026. Ví dụ được rà thủ công về instruction và kiểm cú pháp Bash của các lệnh. Chưa gọi Docker daemon, build image hoặc inspect image thật; các kết quả cần quan sát được mô tả như kế hoạch thử, không phải output đã thu.
Xác định nơi giá trị cần tồn tại
ARG cung cấp đầu vào để Dockerfile dùng trong quá trình build. Nó không tự xuất hiện trong môi trường container được tạo từ image. ENV ghi giá trị môi trường mặc định vào cấu hình image, đồng thời khả dụng cho các instruction tiếp theo trong stage theo tài liệu.
Một ARG vẫn có thể bị lưu thông qua LABEL, ENV, file hoặc metadata build. Vì vậy, “không tự thành biến runtime” không có nghĩa giá trị ấy không để lại dấu vết. Ví dụ chỉ dùng chuỗi demo không nhạy cảm; không dùng ARG hay ENV để giữ secret của pipeline.
Một Dockerfile chỉ để xem metadata
Tạo thư mục thử riêng và lưu file tên Dockerfile:
FROM scratch
ARG BUILD_NOTE=demo
ARG APP_MODE=local
LABEL net.aedev.demo.build-note=$BUILD_NOTE
ENV APP_MODE=$APP_MODEscratch là điểm bắt đầu rỗng, không có shell hoặc chương trình trong image này. Dockerfile không có RUN, COPY hay CMD; mục đích là đọc cấu hình image, không tạo một ứng dụng chạy được. Cách chọn này cũng giúp ví dụ không phụ thuộc một tag Linux cụ thể đang thay đổi.
BUILD_NOTE được dùng để ghi label nên có chỗ xuất hiện trong image, dù bản thân ARG không tự tạo biến môi trường cùng tên. APP_MODE được nối rõ từ ARG sang ENV; đây mới là bước đưa giá trị build vào cấu hình môi trường mặc định.
Thử build và inspect trong môi trường có Docker
Trong đúng thư mục thử, các lệnh sau là cách kiểm chứng đề xuất:
docker build --build-arg BUILD_NOTE=sample --build-arg APP_MODE=release -t aedev-arg-env-demo .
docker image inspect --format '{{json .Config.Env}}' aedev-arg-env-demo
docker image inspect --format '{{json .Config.Labels}}' aedev-arg-env-demoKhi bạn chạy thử, kiểm tra Env có cấu hình APP_MODE với giá trị release và label chứa build-note sample. Không kỳ vọng BUILD_NOTE tự xuất hiện trong Env. Bài chưa thực thi ba lệnh này, nên không báo image ID, thời gian build hoặc kết quả inspect cụ thể.
Không chạy docker run rồi kết luận ví dụ lỗi vì thiếu executable: image metadata này chủ ý không có ứng dụng. Với image ứng dụng thật, có thể kiểm tra thêm môi trường mà process nhận sau khi cấp các override runtime theo cấu hình triển khai.
Tránh nhầm các lớp cấu hình
Đổi --build-arg không thay đổi image đã được build từ trước. ENV trong Dockerfile là giá trị mặc định của image, còn cấu hình môi trường khi tạo container có thể ghi đè theo công cụ chạy. Khi điều tra một giá trị sai, ghi lại image đang dùng và nơi cung cấp giá trị, thay vì chỉ đọc một file env trên máy.
Trong multi-stage build, phạm vi ARG cũng cần được kiểm tra theo stage. Ví dụ này chỉ có một stage, không chứng minh một ARG khai báo ở mọi vị trí đều tự khả dụng ở các stage khác. Đừng mở rộng quy tắc từ fixture nhỏ mà bỏ qua scoping trong tài liệu.
Checklist kiểm tra một giá trị
Hỏi giá trị dùng để chọn cách build, được ghi vào image hay được cấp lúc chạy. Tìm instruction thực sự dùng nó. Sau đó inspect đúng image và quan sát đúng process trong môi trường thử nếu có ứng dụng.
Nếu chỉ cần tham số build, không tự thêm ENV để “cho chắc”. Nếu cần cấu hình runtime, biểu diễn điều đó rõ ràng trong Dockerfile hoặc cấu hình triển khai. Một đường đi dữ liệu nhìn thấy được giúp team sửa đúng lớp khi giá trị không giống mong muốn.
