# Docker 构建问题排查指南

## 常见构建错误

### 1. 依赖安装失败
**症状**：软件包无法下载或安装

**解决方案**：
- 检查网络连接
- 更新 `sources.list` 或 `repositories`
- 手动安装缺失依赖
- 检查架构兼容性

### 2. 交叉编译问题
**症状**：编译过程中出现架构不兼容错误

**诊断步骤**：
- 验证交叉编译工具链
- 检查 `CMakeLists.txt` 配置
- 降低并行编译作业数
- 查看完整编译日志

### 3. BuildX 配置问题
**症状**：多架构构建失败

**排查清单**：
- 确认 BuildX 实例正常
- 检查 `--platform` 参数
- 验证 Docker 版本兼容性
- 重置 BuildX 实例

### 4. 镜像大小异常
**症状**：构建镜像unexpectedly大

**优化建议**：
- 使用多阶段构建
- 删除不必要的构建缓存
- 精简基础镜像
- 仅复制必要的二进制文件

## 调试工具和命令

### BuildX 诊断
```bash
docker buildx ls
docker buildx inspect
docker buildx debug
```

### 构建日志分析
```bash
docker buildx build --progress=plain
```

## 最佳实践

- 始终使用 `--no-cache` 进行初始调试
- 保持 Dockerfile 简洁
- 定期更新基础镜像和依赖
- 遵循最小权限原则