Thông báo lỗi
Hiếm có điều gì làm đình trệ quy trình CI/CD nhanh hơn một lỗi build Docker khó hiểu. Bạn có thể thấy một lỗi như thế này trong terminal hoặc log của mình:
failed to solve: rpc error: code = Unknown desc = failed to solve with frontend dockerfile.v0: failed to create LLB definition: target stage my-app-stage could not be found
Mặc dù các thuật ngữ như rpc error và LLB definition nghe có vẻ phức tạp, nhưng vấn đề thường khá đơn giản. Docker chỉ đơn thuần thông báo rằng nó không thể tìm thấy build stage (giai đoạn build) cụ thể mà bạn đã yêu cầu bằng flag --target. Nó đang tìm kiếm một đích đến không tồn tại.
Nguyên nhân gốc rễ
Nguyên nhân thường nằm ở một trong ba chỗ sau:
- Sai lệch tên gọi: Một lỗi đánh máy đơn giản hoặc sự khác biệt về chữ hoa/chữ thường giữa
Dockerfilevà lệnh build của bạn. - Lỗi cú pháp: Quên từ khóa
AStrong lệnhFROM. - Khai triển biến (Variable Expansion): Các biến môi trường trống hoặc bị null trong quy trình CI/CD (như GitHub Actions) khiến flag
--targetbị bỏ trống.
Cách khắc phục 1: Kiểm tra tính phân biệt chữ hoa chữ thường và lỗi đánh máy
Máy tính rất máy móc. Đối với Docker, build-stage và Build-Stage là hai thực thể hoàn toàn khác nhau. Nếu Dockerfile của bạn định nghĩa một stage là builder nhưng lệnh build của bạn lại gọi BUILDER, quá trình build sẽ thất bại ngay lập tức.
Dockerfile sai:
FROM node:20 AS build-stage
# ... các chỉ dẫn
Lệnh sai:
docker build --target build_stage -t my-app .
Trong ví dụ này, một dấu gạch dưới (_) đã thay thế dấu gạch ngang (-). Sự khác biệt chỉ 1 ký tự này là đủ để làm hỏng quá trình build. Hãy luôn kiểm tra kỹ để đảm bảo chuỗi ký tự sau --target khớp chính xác với tên sau từ khóa AS.
Cách khắc phục 2: Xác minh từ khóa 'AS'
Rất dễ bỏ sót từ khóa AS khi viết Dockerfile theo trí nhớ. Nếu không có nó, Docker sẽ coi chuỗi thứ hai là một phần của tag image hoặc bỏ qua nó hoàn toàn. Điều này có nghĩa là tên stage sẽ không bao giờ được đăng ký trong biểu đồ build (build graph).
Sai:
FROM golang:1.21 builder
Đúng:
FROM golang:1.21 AS builder
Hãy đảm bảo mọi stage mà bạn muốn tham chiếu đều có từ khóa AS đó. Nó là cầu nối liên kết image cơ sở với tên stage tùy chỉnh của bạn.
Cách khắc phục 3: Các vấn đề về BuildKit và 'frontend dockerfile.v0'
Lỗi failed to solve with frontend dockerfile.v0 xuất hiện vì BuildKit (công cụ build hiện đại của Docker) không thể phân tích cấu trúc Dockerfile. Trong Docker Desktop 20.10 trở về sau, BuildKit là mặc định. Nó nhanh, nhưng các thông báo lỗi có thể rất mơ hồ khi cú pháp bị hỏng.
Hãy thử tạm thời vô hiệu hóa BuildKit. Việc này thường buộc trình build cũ (legacy builder) đưa ra thông báo lỗi chi tiết hơn:
DOCKER_BUILDKIT=0 docker build --target my-stage -t my-app .
Nếu trình build cũ hoạt động, vấn đề có thể liên quan đến các ký tự ẩn, chẳng hạn như BOM hoặc kết thúc dòng CRLF, đôi khi làm trình phân tích cú pháp của BuildKit bị nhầm lẫn.
Cách khắc phục 4: Xử lý khai triển biến trong CI/CD
Nếu lỗi này chỉ xảy ra trong GitHub Actions hoặc GitLab CI, hãy kiểm tra các biến môi trường của bạn. Nếu một biến được sử dụng cho tên target bị trống, lệnh shell có thể thực thi như sau:
docker build --target -t my-app .
Docker thấy một chuỗi trống cho target và đưa ra lỗi "stage could not be found". Để debug lỗi này, hãy thêm lệnh echo vào script CI của bạn để in biến đó ra ngay trước bước build. Đảm bảo các secret và biến của bạn được export chính xác vào môi trường runner.
Ví dụ thực tế: Một bản Build đa giai đoạn (Multi-stage) bền vững
Sử dụng template này để tạo một Dockerfile đa giai đoạn sạch sẽ, tránh được các cạm bẫy phổ biến:
# Giai đoạn 1: Build
FROM node:20-alpine AS build_env
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
# Giai đoạn 2: Production
FROM nginx:stable-alpine AS runtime_env
COPY --from=build_env /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
Để chỉ build giai đoạn đầu tiên cho việc unit testing, hãy chạy:
docker build --target build_env -t app-test .
Các bước xác minh
Xác nhận việc khắc phục bằng cách chạy build với flag --target. Nếu thành công, bạn sẽ thấy BuildKit ghi log các bước cụ thể cho stage đó:
# Chạy build
docker build --target build_env -t verification-test .
# Kiểm tra image kết quả
docker images | grep verification-test
Một bản build thành công sẽ xác nhận rằng tên stage đã được nhận diện.
Mẹo phòng ngừa
- Giữ tên đơn giản: Tránh các ký tự đặc biệt. Chỉ nên sử dụng các ký tự chữ số viết thường và dấu gạch ngang.
- Tiêu chuẩn hóa: Sử dụng
base,builder, vàrunnertrên tất cả các dự án của bạn để giảm thiểu sự nhầm lẫn. - Sử dụng Linter: Các công cụ như Hadolint giúp phát hiện việc thiếu từ khóa
ASvà các lỗi cú pháp trước khi bạn kích hoạt quá trình build. - Kiểm tra kết thúc dòng: Nếu bạn phát triển trên Windows nhưng build cho Linux, hãy đảm bảo IDE của bạn được thiết lập thành
LFthay vìCRLF. Các ký tự Windows ẩn đôi khi có thể làm hỏng việc phân tích cú pháp Dockerfile.