Sửa lỗi "go: module not found" trong Go Modules

Lỗi Gặp Phải

Bạn chạy go build, go run, hoặc go get, và gặp lỗi:

go: module not found

Đôi khi lỗi đi kèm thêm thông tin:

go: github.com/some/package@v1.2.3: reading https://proxy.golang.org/github.com/some/package/@v/v1.2.3.info: 404 Not Found
go: module not found

Go không tìm thấy module — không có trong cache cục bộ, không có trên proxy, hoặc file go.mod bị cấu hình sai. Thường có một trong bảy nguyên nhân sau.

Nguyên Nhân

Các nguyên nhân thường đa dạng hơn bạn nghĩ:

Không có file go.mod ở thư mục gốc của project, hoặc bạn đang chạy lệnh Go bên ngoài thư mục module
Đường dẫn module trong go.mod không khớp với những gì code thực sự import
Phiên bản package bạn chỉ định không tồn tại — tag chưa được push, hoặc đã bị xóa
GO111MODULE=off đang được bật, khiến Go bỏ qua go.mod hoàn toàn và quay về chế độ GOPATH
Module private mà proxy công khai proxy.golang.org không thể truy cập
Directive replace trỏ đến đường dẫn cục bộ không còn tồn tại
Cache module bị hỏng hoặc không đầy đủ

Cách Khắc Phục

1. Đảm bảo bạn đang ở trong Go module

Kiểm tra xem go.mod có tồn tại trong thư mục gốc của project không:

ls go.mod

Không có file? Khởi tạo một cái:

go mod init github.com/yourname/yourproject

Sau đó kéo tất cả các dependency cần thiết:

go mod tidy

2. Xác nhận đường dẫn module khớp với import

Mở go.mod và kiểm tra dòng đầu tiên:

module github.com/yourname/yourproject

go 1.21

Đây là một lỗi phổ biến: code của bạn import github.com/yourname/yourproject/utils, nhưng go.mod khai báo module là myapp. Go nhận thấy hai đường dẫn module khác nhau và thất bại. Hãy sửa dòng module để khớp chính xác với những gì các câu lệnh import của bạn sử dụng.

3. Kiểm tra GO111MODULE

Chế độ module đã là mặc định từ Go 1.16. Tuy nhiên, nếu ai đó đặt GO111MODULE=off trong môi trường — có thể trên máy CI cũ — Go sẽ âm thầm bỏ qua file go.mod của bạn.

go env GO111MODULE

Nếu là off, hãy sửa lại:

# Linux/macOS
export GO111MODULE=on

# Windows (PowerShell)
$env:GO111MODULE = "on"

Hoặc chỉ cần xóa nó để dùng giá trị mặc định:

go env -w GO111MODULE=

4. Tải trực tiếp module bị thiếu

Nếu một package cụ thể không có, hãy thêm nó một cách tường minh:

go get github.com/some/package@latest

Ghim vào một phiên bản cụ thể nếu cần:

go get github.com/some/package@v1.2.3

Luôn chạy go mod tidy sau đó để giữ go.mod và go.sum nhất quán:

go mod tidy

5. Kiểm tra các directive replace bị hỏng

Một khối replace trong go.mod trỏ đến đường dẫn cục bộ không tồn tại sẽ gây ra lỗi này mỗi lần:

replace github.com/some/package => ../local-fork

Chạy ls ../local-fork để xác nhận thư mục tồn tại. Nếu đường dẫn đã thay đổi, hãy cập nhật lại. Nếu bạn không còn cần override này nữa, hãy xóa directive đó đi.

6. Xử lý module private

Proxy công khai không thể truy cập các repo private — GitHub Enterprise, GitLab self-hosted, Gitea và các dịch vụ tương tự. Hãy bảo Go bỏ qua proxy cho domain private của bạn:

go env -w GOPRIVATE=gitlab.company.com/*
go env -w GONOSUMCHECK=gitlab.company.com/*

Sau khi cấu hình, Go sẽ tải các module đó trực tiếp từ nguồn thay vì đi qua proxy.golang.org. Bạn cũng cần SSH key hoặc một entry trong ~/.netrc để xác thực.

7. Xóa cache module

Một lần tải không hoàn chỉnh có thể làm hỏng cache và chặn các lần tải sau. Hãy xóa sạch:

go clean -modcache
go mod download

Trên một project lớn, thao tác này có thể tải lại vài trăm megabyte, nhưng đây là cách nhanh nhất để loại trừ các vấn đề về cache.

Xác Nhận Đã Sửa Xong

Kiểm tra xem tất cả các module có được phân giải đúng không:

go mod verify

Kết quả mong đợi:

all modules verified

Sau đó thực hiện build đầy đủ:

go build ./...

Output sạch nghĩa là bạn đã hoàn thành. Để kiểm tra một dependency cụ thể đang đến từ đâu:

go mod graph | grep some/package

Danh Sách Kiểm Tra Nhanh

Không có go.mod? → Chạy go mod init
Đường dẫn module không khớp? → Sửa dòng module trong go.mod
GO111MODULE=off? → Bỏ đặt hoặc đặt thành on
Phiên bản không tồn tại? → Kiểm tra các tag của repo, dùng @latest
Repo private? → Đặt GOPRIVATE cho domain của bạn
Directive replace bị hỏng? → Xác minh đường dẫn hoặc xóa directive
Cache cũ? → go clean -modcache

Vừa Clone Repo?

Nếu bạn vừa clone một project và gặp lỗi này ngay lập tức, hãy chạy go mod download trước khi build. Lệnh này sẽ tải về tất cả các dependency được liệt kê trong go.sum vào cache cục bộ của bạn — tương đương với npm install trong Go.

git clone https://github.com/example/repo
cd repo
go mod download
go build ./...

Hầu hết các lỗi "module not found" khi clone repo mới sẽ biến mất sau bước đơn giản này.