209 lines
3.5 KiB
Markdown
209 lines
3.5 KiB
Markdown
# 故障排除指南
|
||
|
||
## 常见问题
|
||
|
||
### 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：清理模块缓存（推荐）
|
||
|
||
```bash
|
||
# 清理 Go 模块缓存
|
||
go clean -modcache
|
||
|
||
# 重新下载依赖
|
||
go mod download
|
||
|
||
# 整理依赖
|
||
go mod tidy
|
||
```
|
||
|
||
#### 方案2：在调用方项目中解决
|
||
|
||
如果是在调用方项目中遇到此问题：
|
||
|
||
```bash
|
||
# 进入调用方项目目录
|
||
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：使用代理（如果网络问题）
|
||
|
||
```bash
|
||
# 设置 Go 代理（国内用户推荐）
|
||
go env -w GOPROXY=https://goproxy.cn,direct
|
||
|
||
# 或者使用官方代理
|
||
go env -w GOPROXY=https://proxy.golang.org,direct
|
||
```
|
||
|
||
#### 方案4：强制更新依赖
|
||
|
||
```bash
|
||
# 强制更新所有依赖
|
||
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
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 配置 GOPRIVATE
|
||
go env -w GOPRIVATE=git.toowon.com
|
||
|
||
# 配置 Git 认证（如果需要）
|
||
git config --global url."git@git.toowon.com:".insteadOf "https://git.toowon.com/"
|
||
```
|
||
|
||
详细说明请参考 [SETUP.md](./SETUP.md)
|
||
|
||
### 3. 版本标签不存在
|
||
|
||
**错误信息：**
|
||
```
|
||
go: git.toowon.com/jimmy/go-common@v0.0.1: invalid version: unknown revision
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
1. 确认版本标签已创建并推送：
|
||
```bash
|
||
# 在库项目中查看标签
|
||
git tag -l
|
||
|
||
# 如果标签不存在，创建并推送
|
||
git tag -a v0.0.1 -m "Release v0.0.1"
|
||
git push origin v0.0.1
|
||
```
|
||
|
||
2. 在调用方项目中清理缓存后重试：
|
||
```bash
|
||
go clean -modcache
|
||
go get git.toowon.com/jimmy/go-common@v0.0.1
|
||
```
|
||
|
||
### 4. 依赖版本冲突
|
||
|
||
**错误信息：**
|
||
```
|
||
go: conflicting versions for module
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 查看依赖树
|
||
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
|
||
```
|
||
|
||
**解决方案：**
|
||
|
||
```bash
|
||
# 使用国内代理
|
||
go env -w GOPROXY=https://goproxy.cn,direct
|
||
|
||
# 或者使用七牛云代理
|
||
go env -w GOPROXY=https://goproxy.io,direct
|
||
|
||
# 禁用代理（直接访问）
|
||
go env -w GOPROXY=direct
|
||
```
|
||
|
||
## 通用排查步骤
|
||
|
||
如果遇到其他问题，按以下步骤排查：
|
||
|
||
1. **清理缓存**
|
||
```bash
|
||
go clean -modcache
|
||
```
|
||
|
||
2. **验证模块**
|
||
```bash
|
||
go mod verify
|
||
```
|
||
|
||
3. **整理依赖**
|
||
```bash
|
||
go mod tidy
|
||
```
|
||
|
||
4. **查看依赖图**
|
||
```bash
|
||
go mod graph
|
||
```
|
||
|
||
5. **查看模块信息**
|
||
```bash
|
||
go list -m all
|
||
```
|
||
|
||
6. **检查 Go 环境**
|
||
```bash
|
||
go env
|
||
```
|
||
|
||
## 获取帮助
|
||
|
||
如果以上方法都无法解决问题，请：
|
||
|
||
1. 检查 Go 版本（建议使用 Go 1.21 或更高版本）
|
||
```bash
|
||
go version
|
||
```
|
||
|
||
2. 查看详细的错误信息
|
||
```bash
|
||
go get -v git.toowon.com/jimmy/go-common@v0.0.1
|
||
```
|
||
|
||
3. 检查项目仓库是否有对应的版本标签
|
||
|
||
4. 联系项目维护者
|
||
|