Bạn thêm một biến vào .env, tạo lại service rồi ứng dụng vẫn không đọc được nó. Trước khi sửa code, hãy tách hai câu hỏi: Compose dùng giá trị nào để dựng cấu hình, và container được nhận biến nào khi khởi tạo?
Bài dựa trên tài liệu Docker Compose hiện hành được kiểm tra ngày 28/10/2026. Các ví dụ là phần bổ sung cho một dự án Compose đã có service api chạy được. YAML và cú pháp shell được kiểm tra tĩnh; lượt biên tập chưa chạy Docker daemon hoặc xác nhận output bằng Compose thực tế.
1. Nhìn hai tầng cấu hình riêng
Ở tầng đầu, Compose đọc biểu thức như ${APP_COLOR:-blue} và thay bằng giá trị phù hợp từ nguồn nội suy. Ở tầng thứ hai, các thuộc tính service như environment và env_file xác định những biến được truyền vào container.
Một tên biến có thể xuất hiện ở cả hai tầng, nhưng không vì thế mà hai bước là một. .env của Compose không tự chuyển toàn bộ nội dung của nó thành environment cho mọi container. Bạn cần một khai báo service thể hiện ý định truyền giá trị vào.
2. Dùng dữ liệu giả để kiểm tra xung đột
Trong thư mục dự án thử nghiệm, tạo .env với nội dung:
APP_COLOR=greenTạo thêm file runtime.env để dùng làm environment file của service:
APP_COLOR=red
EXTRA_LABEL=demoThêm phần cấu hình sau vào service api hiện có. Giữ nguyên image hoặc build hợp lệ của dự án; block này chưa phải file Compose hoàn chỉnh:
services:
api:
env_file:
- runtime.env
environment:
APP_COLOR: "${APP_COLOR:-blue}"Với giả định shell chưa đặt APP_COLOR và Compose tìm đúng .env nói trên, biểu thức được nội suy thành green. Service còn có giá trị red trong runtime.env, nhưng khai báo environment của service ghi đè giá trị cùng tên đó. EXTRA_LABEL vẫn đến từ runtime.env.
Đây là kết quả mong đợi theo quy tắc tài liệu, chưa phải output chạy thực tế của lượt biên tập. Bảng dưới giúp bạn tự kiểm chứng trên môi trường thử nghiệm.
3. Thay một yếu tố mỗi lần
| Thay đổi so với ví dụ | APP_COLOR mong đợi trong service |
|---|---|
| Không có biến cùng tên trong shell | green từ biểu thức đã nội suy |
| Shell đặt APP_COLOR=yellow | yellow từ biểu thức đã nội suy |
| Bỏ riêng mục environment của api | red từ runtime.env |
| Bỏ cả environment và env_file của api | Không được truyền chỉ nhờ .env; còn tùy ENV của image |
Hàng cuối không cam kết biến chắc chắn vắng mặt, vì image của bạn có thể đã khai báo ENV. Chính vì vậy, cần đọc cả cấu hình image nếu đang điều tra một giá trị không rõ nguồn.
Dùng giá trị giả khác nhau ở mỗi nguồn giúp bạn nhìn ra nguồn nào thắng. Đừng đặt cùng một giá trị ở mọi file rồi dựa vào kết quả giống nhau để kết luận đã hiểu thứ tự ưu tiên.
4. Kiểm tra cấu hình Compose trước container
docker compose version
docker compose config --quiet
docker compose config --environment
docker compose configCác lệnh config giúp xem cấu hình đã được xử lý và nguồn dùng cho nội suy. Chạy chúng trong đúng thư mục, với đúng các file Compose và option mà dự án sử dụng. Khi kiểm tra ví dụ này, chỉ dùng file chứa dữ liệu giả để output có thể chia sẻ mà không lộ cấu hình riêng.
Bạn cũng có thể thử một giá trị shell cho riêng lời gọi:
APP_COLOR=yellow docker compose configSau đó kiểm tra environment trong một container thử nghiệm của service bằng công cụ mà image có sẵn. Ví dụ, docker compose exec api printenv APP_COLOR chỉ phù hợp nếu container đang chạy và có lệnh printenv. Không giả định mọi image tối giản đều có shell hoặc tiện ích giống nhau.
Lỗi thường gặp
--env-file ở CLI phục vụ nguồn biến cho Compose và thuộc tính env_file dưới service là hai vị trí khác nhau. Khi đổi nguồn, hãy chỉ rõ bạn đang đổi tầng nội suy hay tầng environment của container.
Biểu thức :- dùng giá trị mặc định khi biến chưa đặt hoặc rỗng; dấu - không có dấu hai chấm có quy tắc khác với trường hợp rỗng. Đừng sửa một ký tự trong biểu thức mà không thử cả biến thiếu lẫn chuỗi rỗng.
Nếu file đã sửa nhưng container cũ vẫn có giá trị cũ, kiểm tra quy trình cập nhật service. Cấu hình mong muốn trên máy không tự chứng minh container đang chạy đã được tạo với cấu hình đó. Việc tạo lại container cần được lên kế hoạch theo môi trường của bạn.
Bước tiếp theo
Lập một bảng nguồn cấu hình nhỏ cho các biến quan trọng: ai nội suy, ai truyền vào container và ứng dụng đọc ở đâu. Khi các tầng đã rõ, bạn có thể giảm khai báo trùng và làm tài liệu thiết lập dễ theo hơn. Bài chưa thực hiện triển khai hoặc thay đổi container nào của hệ thống đang chạy.
