# 故障排除指南

## 常见问题

### 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. 联系项目维护者