Khắc phục lỗi 'go: inconsistent vendoring' trong Go Modules

Tìm hiểu về lỗi

Lỗi go: inconsistent vendoring xảy ra khi tệp go.mod và thư mục vendor/ của bạn không đồng bộ với nhau. Khi bạn sử dụng cờ -mod=vendor (thường là mặc định trong các phiên bản Go hiện đại nếu tồn tại thư mục vendor), bộ công cụ Go sẽ kiểm tra vendor/modules.txt để đảm bảo nó khớp với những gì được định nghĩa trong go.mod.

Nếu bạn thêm một dependency mới vào go.mod nhưng quên cập nhật thư mục vendor, hoặc nếu việc merge bằng git dẫn đến sự sai lệch, Go sẽ dừng quá trình build và thông báo lỗi này để ngăn bạn build với mã nguồn không chính xác hoặc bị thiếu.

go: inconsistent vendoring in /app:
    github.com/foo/bar@v1.2.3: is explicitly required in go.mod, but not marked as explicit in vendor/modules.txt

Các bước khắc phục

Bước 1: Đồng bộ hóa các dependency

Nguyên nhân phổ biến nhất đơn giản là do quên chạy lệnh vendor sau khi thêm một package mới. Hãy chạy các lệnh sau tại thư mục gốc của dự án:

# Dọn dẹp các dependency không sử dụng và thêm các dependency còn thiếu vào go.mod
go mod tidy

# Cập nhật thư mục vendor để khớp với go.mod
go mod vendor

Lệnh go mod vendor sẽ ghi đè lại thư mục vendor/ và tạo lại vendor/modules.txt, điều này sẽ giải quyết sự không nhất quán.

Bước 2: Kiểm tra xung đột khi Merge Git

Nếu bạn vừa mới merge một branch, có khả năng go.mod đã được cập nhật nhưng vendor/modules.txt thì chưa, hoặc ngược lại. Nếu lệnh go mod vendor không khắc phục được ngay, hãy thử xóa hoàn toàn thư mục vendor và tạo lại nó:

rm -rf vendor/
go mod tidy
go mod vendor

Bước 3: Khắc phục sự không nhất quán trong Docker

Nếu lỗi này xảy ra bên trong một Docker container nhưng không xảy ra trên máy cục bộ của bạn, hãy kiểm tra Dockerfile. Thông thường, các lập trình viên copy go.mod và go.sum nhưng quên copy thư mục vendor, hoặc họ chạy go build với giả định rằng container sẽ tải xuống các dependency trong khi môi trường được thiết lập để sử dụng thư mục vendor.

Đảm bảo Dockerfile của bạn bao gồm thư mục vendor nếu bạn có ý định sử dụng nó:

# Ví dụ đoạn mã Dockerfile
COPY go.mod go.sum ./
COPY vendor/ vendor/
RUN go build -mod=vendor -o myapp

Ngoài ra, nếu bạn không muốn sử dụng thư mục vendor trong Docker, hãy đảm bảo thư mục vendor được bỏ qua thông qua .dockerignore và không sử dụng cờ -mod=vendor.

Bước 4: Kiểm tra phiên bản Go

Đôi khi, các phiên bản Go khác nhau xử lý vendoring theo cách khác nhau. Đảm bảo rằng phiên bản Go được sử dụng để chạy go mod vendor khớp với phiên bản được sử dụng để build ứng dụng. Bạn có thể kiểm tra phiên bản của mình bằng lệnh:

go version

Xác minh: Cách kiểm tra xem lỗi đã được khắc phục chưa

Để xác minh rằng sự không nhất quán đã biến mất, hãy chạy lệnh build và ép buộc sử dụng thư mục vendor:

go build -mod=vendor ./...

Nếu lệnh hoàn tất mà không có thông báo lỗi nào, tệp vendor/modules.txt hiện đã được đồng bộ hóa chính xác với go.mod. Bạn cũng sẽ thấy rằng vendor/modules.txt hiện đã chứa package bị thiếu được đề cập trong thông báo lỗi.

Mẹo chuyên nghiệp để tránh lỗi này

• Kiểm tra CI/CD: Thêm một bước trong pipeline CI của bạn để chạy go mod tidy và go mod vendor, sau đó kiểm tra xem git status --porcelain có trống hay không. Điều này đảm bảo không ai quên commit thư mục vendor đã cập nhật.
• Môi trường Go: Nếu bạn thực sự không cần thư mục vendor, hãy xóa nó. Go modules hoạt động hoàn hảo bằng cách tải các dependency vào module cache ($GOPATH/pkg/mod) mà không cần thư mục vendor cục bộ.
• Cờ Read-Only: Trong môi trường build, hãy sử dụng go build -mod=readonly để đảm bảo quá trình build sẽ thất bại nếu go.mod cần cập nhật, thay vì để nó tự động thay đổi các tệp một cách âm thầm.