Go Modules 常见问题排查 #

依赖下载问题 #

问题：go: module xxx: no matching versions for query #

错误信息：

text

go: module github.com/user/package: no matching versions for query "latest"

可能原因：

模块不存在或名称错误
网络连接问题
代理配置问题
私有模块未配置

解决方案：

bash

# 1. 检查模块名称是否正确
go get github.com/correct/package@latest

# 2. 检查网络连接
ping github.com

# 3. 配置代理
go env -w GOPROXY=https://goproxy.cn,direct

# 4. 如果是私有模块
go env -w GOPRIVATE=github.com/mycompany/*

问题：go: get xxx: dial tcp: lookup proxy.golang.org #

错误信息：

text

go: get github.com/gin-gonic/gin: dial tcp: lookup proxy.golang.org: no such host

解决方案：

bash

# 1. 检查 DNS 配置
cat /etc/resolv.conf

# 2. 使用国内代理
go env -w GOPROXY=https://goproxy.cn,direct

# 3. 或使用直连
go env -w GOPROXY=direct

问题：go: download xxx: connection refused #

错误信息：

text

go: github.com/gin-gonic/gin@v1.9.1: download ... connection refused

解决方案：

bash

# 1. 检查代理设置
go env GOPROXY

# 2. 配置正确的代理
go env -w GOPROXY=https://goproxy.cn,direct

# 3. 检查防火墙设置
# Linux
sudo ufw status

# macOS
# 系统偏好设置 -> 安全性与隐私 -> 防火墙

# 4. 使用代理服务器
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

问题：go: download xxx: timeout #

错误信息：

text

go: github.com/gin-gonic/gin@v1.9.1: download timeout

解决方案：

bash

# 1. 使用国内镜像
go env -w GOPROXY=https://goproxy.cn,direct

# 2. 增加超时时间
go env -w GOFLAGS="-timeout=10m"

# 3. 重试下载
go clean -modcache
go mod download

版本相关问题 #

问题：go: module xxx: version “latest” invalid #

错误信息：

text

go: module github.com/user/package: version "latest" invalid

解决方案：

bash

# 使用正确的语法
go get github.com/user/package@latest

# 或指定具体版本
go get github.com/user/package@v1.0.0

问题：go: found xxx in xxx but not in go.mod #

错误信息：

text

go: found github.com/gin-gonic/gin in github.com/gin-gonic/gin v1.9.1 but not in go.mod

解决方案：

bash

# 运行 tidy 整理依赖
go mod tidy

# 或手动添加
go get github.com/gin-gonic/gin@v1.9.1

问题：go: xxx: invalid version: unknown revision #

错误信息：

text

go: github.com/user/package@v1.0.0: invalid version: unknown revision v1.0.0

解决方案：

bash

# 1. 检查版本是否存在
go list -m -versions github.com/user/package

# 2. 使用存在的版本
go get github.com/user/package@v1.0.1

# 3. 如果是私有模块，确保有访问权限
go env -w GOPRIVATE=github.com/user/*

问题：go: xxx: ambiguous import #

错误信息：

text

go: ambiguous import: found package github.com/user/package in multiple modules

解决方案：

bash

# 1. 查看重复的模块
go list -m all | grep package

# 2. 使用 replace 解决
# go.mod
replace github.com/user/package => github.com/user/package v1.0.0

# 3. 或使用特定版本
go get github.com/user/package@v1.0.0

依赖冲突问题 #

问题：go: version constraints conflict #

错误信息：

text

go: github.com/common/pkg: version constraints conflict

解决方案：

bash

# 1. 查看依赖关系
go mod graph | grep common/pkg

# 2. 使用 replace 强制版本
# go.mod
replace github.com/common/pkg => github.com/common/pkg v1.5.0

# 3. 或更新冲突的依赖
go get github.com/pkgA@latest
go get github.com/pkgB@latest
go mod tidy

问题：go: missing go.sum entry #

错误信息：

text

go: missing go.sum entry for module providing package xxx

解决方案：

bash

# 运行 tidy 生成 go.sum
go mod tidy

# 或手动下载
go mod download

问题：go: xxx requires xxx but xxx is used #

错误信息：

text

go: github.com/pkgA requires github.com/common@v1.0.0 but github.com/common@v2.0.0 is used

解决方案：

bash

# 1. 查看依赖图
go mod graph | grep common

# 2. 使用 replace 统一版本
# go.mod
replace github.com/common => github.com/common v2.0.0

# 3. 或降级依赖
go get github.com/pkgA@v1.0.0

代理相关问题 #

问题：proxy.golang.org 连接超时 #

错误信息：

text

go: proxy.golang.org/xxx: dial tcp: connection timeout

解决方案：

bash

# 使用国内代理
go env -w GOPROXY=https://goproxy.cn,direct

# 或使用阿里云镜像
go env -w GOPROXY=https://mirrors.aliyun.com/goproxy/,direct

问题：私有模块无法下载 #

错误信息：

text

go: gitlab.company.com/team/project@v1.0.0: reading ... 404 Not Found

解决方案：

bash

# 1. 配置私有模块
go env -w GOPRIVATE=gitlab.company.com/*

# 2. 配置 Git 认证
git config --global url."git@gitlab.company.com:".insteadOf "https://gitlab.company.com/"

# 3. 配置 .netrc
# ~/.netrc
machine gitlab.company.com
login username
password token

# 4. 设置权限
chmod 600 ~/.netrc

问题：校验和不匹配 #

错误信息：

text

go: verifying module: checksum mismatch

解决方案：

bash

# 1. 清理缓存
go clean -modcache

# 2. 删除 go.sum 重新生成
rm go.sum
go mod tidy

# 3. 如果是私有模块，跳过校验
go env -w GONOSUMDB=github.com/mycompany/*

go.mod/go.sum 问题 #

问题：go.mod 文件不存在 #

错误信息：

text

go: cannot find module providing package xxx: working directory is not part of a module

解决方案：

bash

# 初始化模块
go mod init myproject

# 或在正确的目录运行
cd /path/to/project
go build

问题：go.mod 文件格式错误 #

错误信息：

text

go: errors parsing go.mod:

解决方案：

bash

# 1. 格式化 go.mod
go mod edit -fmt

# 2. 检查语法
cat go.mod

# 3. 重新生成
rm go.mod go.sum
go mod init myproject
go mod tidy

问题：go.sum 冲突 #

错误信息：

text

go: conflicting go.sum entries

解决方案：

bash

# 1. 删除 go.sum 重新生成
rm go.sum
go mod tidy

# 2. 或手动解决冲突
# 编辑 go.sum，保留正确的校验和
go mod verify

构建问题 #

问题：build cannot find module #

错误信息：

text

build command-line-arguments: cannot find module for package xxx

解决方案：

bash

# 1. 确保在模块目录
pwd

# 2. 整理依赖
go mod tidy

# 3. 下载依赖
go mod download

# 4. 重新构建
go build

问题：package xxx is not in GOROOT #

错误信息：

text

package xxx is not in GOROOT

解决方案：

bash

# 1. 检查 import 路径
# 确保使用正确的包路径

# 2. 如果是外部包，确保已添加依赖
go get github.com/user/package

# 3. 整理依赖
go mod tidy

问题：vendor 目录问题 #

错误信息：

text

go: inconsistent vendor

解决方案：

bash

# 重新生成 vendor
rm -rf vendor
go mod vendor

# 或不使用 vendor
go build -mod=mod

环境问题 #

问题：GOPATH 模式问题 #

错误信息：

text

go: modules disabled by GO111MODULE=off

解决方案：

bash

# 启用模块模式
go env -w GO111MODULE=on

# 或使用自动模式
go env -w GO111MODULE=auto

问题：Go 版本不兼容 #

错误信息：

text

go: module xxx requires Go >= 1.21

解决方案：

bash

# 1. 检查当前 Go 版本
go version

# 2. 升级 Go 版本
# macOS
brew upgrade go

# Linux
wget https://go.dev/dl/go1.21.0.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.21.0.linux-amd64.tar.gz

# 3. 或修改 go.mod 中的版本要求
go mod edit -go=1.20

问题：缓存损坏 #

错误信息：

text

go: cache corruption

解决方案：

bash

# 清理所有缓存
go clean -cache -modcache -testcache

# 重新下载
go mod download

私有模块问题 #

问题：无法访问私有仓库 #

错误信息：

text

go: gitlab.company.com/team/project@v1.0.0: git ls-remote failed

解决方案：

bash

# 1. 配置私有模块
go env -w GOPRIVATE=gitlab.company.com/*

# 2. 配置 Git SSH
git config --global url."git@gitlab.company.com:".insteadOf "https://gitlab.company.com/"

# 3. 测试 Git 访问
git ls-remote gitlab.company.com/team/project

# 4. 配置 .netrc（如果使用 HTTPS）
# ~/.netrc
machine gitlab.company.com
login username
password token

问题：私有模块校验失败 #

错误信息：

text

go: verifying gitlab.company.com/team/project@v1.0.0: checksum mismatch

解决方案：

bash

# 跳过私有模块校验
go env -w GONOSUMDB=gitlab.company.com/*

# 或使用 GOPRIVATE（自动设置 GONOSUMDB）
go env -w GOPRIVATE=gitlab.company.com/*

问题：私有模块代理问题 #

错误信息：

text

go: gitlab.company.com/team/project@v1.0.0: 404 Not Found

解决方案：

bash

# 配置私有模块不走代理
go env -w GOPRIVATE=gitlab.company.com/*
go env -w GONOPROXY=gitlab.company.com/*

# 或使用直连
go env -w GOPROXY=https://goproxy.cn,https://proxy.golang.org,direct

调试技巧 #

查看详细信息 #

bash

# 查看构建详细信息
go build -x

# 查看模块解析过程
go build -x -v

# 查看 go.mod 解析
go list -m -json all

# 查看依赖图
go mod graph

# 查看为什么需要某个依赖
go mod why github.com/gin-gonic/gin

网络调试 #

bash

# 测试代理连接
curl -I https://goproxy.cn/github.com/gin-gonic/gin/@v/list

# 查看代理返回
curl https://goproxy.cn/github.com/gin-gonic/gin/@v/list

# 测试模块下载
go mod download -x -json github.com/gin-gonic/gin@v1.9.1

缓存调试 #

bash

# 查看缓存位置
go env GOMODCACHE

# 验证缓存
go mod verify

# 查看特定模块缓存
ls $(go env GOMODCACHE)/github.com/gin-gonic

# 清理特定模块缓存
rm -rf $(go env GOMODCACHE)/github.com/problematic

常用排查流程 #

依赖下载失败排查 #

text

1. 检查网络连接
   └── ping github.com

2. 检查代理配置
   └── go env GOPROXY

3. 尝试国内代理
   └── go env -w GOPROXY=https://goproxy.cn,direct

4. 清理缓存重试
   └── go clean -modcache && go mod download

5. 检查私有模块配置
   └── go env GOPRIVATE

版本冲突排查 #

text

1. 查看依赖图
   └── go mod graph | grep problematic

2. 查看依赖来源
   └── go mod why -m problematic/pkg

3. 列出所有版本
   └── go list -m -versions problematic/pkg

4. 使用 replace 解决
   └── go mod edit -replace=problematic/pkg=problematic/pkg@v1.0.0

5. 重新整理
   └── go mod tidy

构建失败排查 #

text

1. 检查模块模式
   └── go env GO111MODULE

2. 检查 go.mod
   └── cat go.mod

3. 整理依赖
   └── go mod tidy

4. 验证依赖
   └── go mod verify

5. 清理缓存重建
   └── go clean -cache && go build

快速参考 #

常用修复命令 #

bash

# 整理依赖
go mod tidy

# 清理缓存
go clean -modcache

# 重新下载
go mod download

# 验证依赖
go mod verify

# 查看依赖
go list -m all

# 更新依赖
go get -u=patch

环境配置 #

bash

# 配置代理
go env -w GOPROXY=https://goproxy.cn,direct

# 配置私有模块
go env -w GOPRIVATE=github.com/mycompany/*

# 启用模块模式
go env -w GO111MODULE=on

Git 配置 #

bash

# SSH 替代 HTTPS
git config --global url."git@github.com:".insteadOf "https://github.com/"

# 查看配置
git config --global --list

Go Modules 常见问题排查 #

依赖下载问题 #

问题：go: module xxx: no matching versions for query #

问题：go: get xxx: dial tcp: lookup proxy.golang.org #

问题：go: download xxx: connection refused #

问题：go: download xxx: timeout #

版本相关问题 #

问题：go: module xxx: version “latest” invalid #

问题：go: found xxx in xxx but not in go.mod #

问题：go: xxx: invalid version: unknown revision #

问题：go: xxx: ambiguous import #

依赖冲突问题 #

问题：go: version constraints conflict #

问题：go: missing go.sum entry #

问题：go: xxx requires xxx but xxx is used #

代理相关问题 #

问题：proxy.golang.org 连接超时 #

问题：私有模块无法下载 #

问题：校验和不匹配 #

go.mod/go.sum 问题 #

问题：go.mod 文件不存在 #

问题：go.mod 文件格式错误 #

问题：go.sum 冲突 #

构建问题 #

问题：build cannot find module #

问题：package xxx is not in GOROOT #

问题：vendor 目录问题 #

环境问题 #

问题：GOPATH 模式问题 #

问题：Go 版本不兼容 #

问题：缓存损坏 #

私有模块问题 #

问题：无法访问私有仓库 #

问题：私有模块校验失败 #

问题：私有模块代理问题 #

调试技巧 #

查看详细信息 #

网络调试 #

缓存调试 #

常用排查流程 #

依赖下载失败排查 #

版本冲突排查 #

构建失败排查 #

快速参考 #

常用修复命令 #

环境配置 #

Git 配置 #

相关文档 #