# 90 排错手册

## 网络问题（最常见）

### WSL2 拉不到国外源（GitHub / PyPI）

**症状**：
- `curl` 返回 9-14 字节（HTML 错误页）
- `git clone` 慢到 0 KB/s 或报 `early EOF`
- `apt update` 卡住

**解法 A：用 Windows 浏览器下载，WSL2 拿本地文件**

1. Windows 浏览器下到 `D:\xxx`
2. WSL2 读：`/mnt/d/xxx`

**解法 B：换国内镜像源**

```bash
# pip 走清华
uv pip install xxx --extra-index-url https://pypi.tuna.tsinghua.edu.cn/simple

# Hugging Face 走镜像
export HF_ENDPOINT=https://hf-mirror.com

# apt 走阿里云
sudo sed -i 's/archive.ubuntu.com/mirrors.aliyun.com/g' /etc/apt/sources.list
sudo apt update
```

**解法 C：让 WSL2 走 Windows 代理**

如果 Windows 上有 clash/v2ray（默认端口 7890）：
```bash
# 临时
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890

# 永久
echo 'export http_proxy=http://127.0.0.1:7890' >> ~/.bashrc
echo 'export https_proxy=http://127.0.0.1:7890' >> ~/.bashrc
```

## 安装问题

### Ollama 装时报 "zstd not found"

```bash
sudo apt install -y zstd
```
然后重装。

### WSL2 透传不到 GPU

按顺序排查：

```bash
# 1. 确认 WSL2 版本
wsl --list --verbose
# VERSION 列必须 = 2

# 2. 更新 WSL2 内核（PowerShell 管理员）
wsl --update

# 3. 重启 WSL2（PowerShell）
wsl --shutdown
# 重新打开 Ubuntu 终端

# 4. 在 Ubuntu 内验证
nvidia-smi
```

如果还不行：
- 确认 Windows 端 `nvidia-smi` 能看到 5060 Ti
- 重新启动整个 WSL2 服务（`services.msc` → `LxssManager` → 重启）

### `nvidia-smi` 在 Ubuntu 报错 "command not found"

说明 `PATH` 没设对。回到 [03 章 WSL2 + CUDA 12.8](./03-wsl2-ubuntu.md) 重新加 PATH。

### `uv pip install` 报 "the argument --index-url cannot be used multiple times"

去掉 `-i` 或不要同时加两个 `--index-url`。`uv` 用 `--index-url`（PyTorch 专有源）+ `--extra-index-url`（清华源）的组合方式，**不能**两个 `--index-url`。

### PyTorch 装完 import 报 `libcudart.so not found`

CUDA Toolkit 没装好，重装 [03 章](./03-wsl2-ubuntu.md)。

### PyTorch 输出 `CUDA: False`

```bash
# 排查
python -c "import torch; print(torch.version.cuda)"
# 应输出 12.8

ls /usr/local/cuda/lib64/libcudart.so*
# 应有文件存在
```

## 性能问题

### Ollama 跑模型慢（< 5 tokens/s）

- 检查是不是量化版本太重（如 32B 跑 16G 显存必慢）
- 关掉其他吃 GPU 的程序（`nvidia-smi` 看 GPU-Util）
- 试试更小的模型（7b 替代 14b）

### ComfyUI 出图慢

- 第一次出图编译 kernel，慢 2-3 分钟（正常）
- 之后每张 5-10 秒是 Flux.1-dev fp8 正常速度
- 调小分辨率（512x512 → 1024x1024 慢 4 倍）

## 显存问题

### 跑 14B 模型 OOM (Out of Memory)

```bash
# 关掉其他模型
ollama stop qwen2.5:7b

# 用更小的量化版本
ollama pull qwen2.5:7b
```

### ComfyUI 出图 OOM

1. 调小图片尺寸（1024 → 768）
2. 启用 FP8 attention
3. 关掉 ControlNet / LoRA

## 黑屏 / 驱动冲突

### 千万别在 WSL2 装 NVIDIA 驱动

会和 Windows 驱动打架 → **整个系统黑屏**。如果已经装了：
1. 重启进 Windows 安全模式
2. 用 DDU 卸载
3. 正常启动

### 重装 WSL2 内核

```powershell
# PowerShell 管理员
wsl --shutdown
wsl --update
wsl --unregister Ubuntu-24.04   # 注意：会删 Ubuntu 内所有数据
wsl --install -d Ubuntu-24.04
```

## 工具脚本

### 一键检查所有验证

```bash
cat > /tmp/check.sh << 'EOF'
echo "=== nvidia-smi ==="
nvidia-smi
echo ""
echo "=== nvcc ==="
nvcc --version
echo ""
echo "=== ollama ==="
ollama --version
ollama list
echo ""
echo "=== PyTorch ==="
source /mnt/d/llm-code/.venv/bin/activate
python -c "import torch; print('CUDA:', torch.cuda.is_available(), '| GPU:', torch.cuda.get_device_name(0))"
EOF
chmod +x /tmp/check.sh
bash /tmp/check.sh
```

跑这个能一次性看到所有组件状态。