go-common/TROUBLESHOOTING.md

故障排除指南

常见问题

1. 伪版本错误 (Pseudo-version error)

错误信息：

go: github.com/pmezard/go-difflib@v1.1.1-0.20181226105442-5d4384ee4fb2: invalid pseudo-version: preceding tag (v1.1.0) not found

原因：

• Go 模块缓存损坏
• 依赖版本冲突
• 间接依赖使用了无效的伪版本

解决方案：

方案1：清理模块缓存（推荐）

# 清理 Go 模块缓存
go clean -modcache

# 重新下载依赖
go mod download

# 整理依赖
go mod tidy

方案2：在调用方项目中解决

如果是在调用方项目中遇到此问题：

# 进入调用方项目目录
cd /path/to/your/project

# 清理模块缓存
go clean -modcache

# 删除 go.sum 文件（可选，会自动重新生成）
rm go.sum

# 重新获取依赖
go get git.toowon.com/jimmy/go-common@v0.0.1

# 整理依赖
go mod tidy

方案3：使用代理（如果网络问题）

# 设置 Go 代理（国内用户推荐）
go env -w GOPROXY=https://goproxy.cn,direct

# 或者使用官方代理
go env -w GOPROXY=https://proxy.golang.org,direct

方案4：强制更新依赖

# 强制更新所有依赖
go get -u ./...

# 或者更新特定依赖
go get -u git.toowon.com/jimmy/go-common@latest

2. 私有仓库访问问题

错误信息：

go: git.toowon.com/jimmy/go-common@v0.0.1: unrecognized import path

解决方案：

# 配置 GOPRIVATE
go env -w GOPRIVATE=git.toowon.com

# 配置 Git 认证（如果需要）
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"

详细说明请参考 SETUP.md

3. 版本标签不存在

错误信息：

go: git.toowon.com/jimmy/go-common@v0.0.1: invalid version: unknown revision

解决方案：

1. 确认版本标签已创建并推送：

   # 在库项目中查看标签
   git tag -l
   
   # 如果标签不存在，创建并推送
   git tag -a v0.0.1 -m "Release v0.0.1"
   git push origin v0.0.1
   

2. 在调用方项目中清理缓存后重试：

   go clean -modcache
   go get git.toowon.com/jimmy/go-common@v0.0.1
   

4. 依赖版本冲突

错误信息：

go: conflicting versions for module

解决方案：

# 查看依赖树
go mod graph | grep conflicting-module

# 更新冲突的依赖
go get -u conflicting-module@latest

# 整理依赖
go mod tidy

5. 网络连接问题

错误信息：

dial tcp: lookup proxy.golang.org: no such host

解决方案：

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

# 或者使用七牛云代理
go env -w GOPROXY=https://goproxy.io,direct

# 禁用代理（直接访问）
go env -w GOPROXY=direct

通用排查步骤

如果遇到其他问题，按以下步骤排查：

1. 清理缓存

   go clean -modcache
   

2. 验证模块

   go mod verify
   

3. 整理依赖

   go mod tidy
   

4. 查看依赖图

   go mod graph
   

5. 查看模块信息

   go list -m all
   

6. 检查 Go 环境

   go env
   

获取帮助

如果以上方法都无法解决问题，请：

1. 检查 Go 版本（建议使用 Go 1.21 或更高版本）

   go version
   

2. 查看详细的错误信息

   go get -v git.toowon.com/jimmy/go-common@v0.0.1
   

3. 检查项目仓库是否有对应的版本标签

4. 联系项目维护者