mxivideo/docs/TROUBLESHOOTING_PYTHON_ENV.md

# Python环境管理器故障排除指南

## 🐛 常见问题和解决方案

### 1. 前端错误

#### 问题：导入错误 - "does not provide an export named 'Python'"

**错误信息**：
```
Uncaught SyntaxError: The requested module '/node_modules/.vite/deps/lucide-react.js?v=d5fe9d89' does not provide an export named 'Python'
```

**原因**：`lucide-react` 库没有 `Python` 图标

**解决方案**：
已修复 - 使用 `Code` 图标替代 `Python` 图标

#### 问题：页面无法加载

**可能原因**：
- 路由配置错误
- 组件导入错误
- TypeScript类型错误

**解决方案**：
1. 检查 `src/App.tsx` 中的路由配置
2. 确保组件正确导入
3. 检查浏览器控制台的错误信息

### 2. 后端错误

#### 问题：Rust命令未注册

**错误信息**：
```
Error: Command not found: get_python_env_status
```

**解决方案**：
1. 确保 `python_env_manager.rs` 已添加到 `commands/mod.rs`
2. 确保命令已在 `lib.rs` 中注册
3. 重新编译：`cargo tauri dev`

#### 问题：Python环境检测失败

**可能原因**：
- Python未安装
- 路径配置错误
- 权限问题

**解决方案**：
1. 检查系统是否安装Python
2. 验证Python在PATH中
3. 以管理员权限运行应用

### 3. 包管理错误

#### 问题：包安装失败

**错误信息**：
```
Failed to install package: pip install failed
```

**可能原因**：
- 网络连接问题
- 包名错误
- 权限不足
- pip未安装

**解决方案**：
1. 检查网络连接
2. 验证包名拼写
3. 确保pip已安装：`python -m pip --version`
4. 尝试手动安装：`python -m pip install package_name`

#### 问题：嵌入式Python设置失败

**错误信息**：
```
Failed to setup embedded Python: setup script failed
```

**解决方案**：
1. 检查网络连接（需要下载Python）
2. 确保有足够磁盘空间（至少500MB）
3. 检查防火墙设置
4. 手动运行设置脚本：`python scripts/setup_embedded_python.py`

### 4. 界面问题

#### 问题：状态不更新

**现象**：操作后状态没有刷新

**解决方案**：
1. 点击"刷新"按钮
2. 检查网络连接
3. 查看浏览器控制台错误
4. 重新加载页面

#### 问题：加载状态卡住

**现象**：页面一直显示"正在加载..."

**解决方案**：
1. 检查后端服务是否正常
2. 查看浏览器网络面板
3. 重新启动应用
4. 检查Rust后端日志

## 🔧 调试步骤

### 1. 前端调试

```javascript
// 在浏览器控制台中测试API调用
import { invoke } from '@tauri-apps/api/core'

// 测试获取环境状态
invoke('get_python_env_status')
  .then(result => console.log('Success:', result))
  .catch(error => console.error('Error:', error))

// 测试安装包
invoke('install_python_package', { packageName: 'requests' })
  .then(result => console.log('Install result:', result))
  .catch(error => console.error('Install error:', error))
```

### 2. 后端调试

在Rust代码中添加调试信息：

```rust
println!("Debug: Checking Python environment...");
println!("Debug: Python path: {:?}", python_path);
println!("Debug: Command output: {:?}", output);
```

### 3. Python环境调试

```cmd
# 检查Python版本
python --version

# 检查pip
python -m pip --version

# 检查已安装包
python -m pip list

# 测试包安装
python -m pip install requests

# 检查Python路径
python -c "import sys; print(sys.executable)"
```

## 📋 检查清单

### 启动前检查

- [ ] Rust代码编译无错误
- [ ] 前端代码无TypeScript错误
- [ ] 所有依赖已安装
- [ ] 路由配置正确

### 运行时检查

- [ ] 页面能正常加载
- [ ] 环境状态正确显示
- [ ] 包列表能正常获取
- [ ] 安装/卸载功能正常
- [ ] 错误信息清晰可读

### 环境检查

- [ ] 系统Python可用（可选）
- [ ] 网络连接正常
- [ ] 磁盘空间充足
- [ ] 权限设置正确

## 🆘 获取帮助

如果问题仍然存在：

1. **查看日志**：
   - 浏览器控制台
   - Tauri开发者工具
   - 系统日志

2. **收集信息**：
   - 操作系统版本
   - Python版本
   - 错误信息截图
   - 重现步骤

3. **尝试最小化重现**：
   - 创建最简单的测试用例
   - 排除其他因素干扰

4. **检查相关文档**：
   - Tauri官方文档
   - Python官方文档
   - 相关库的文档

## 🔄 重置和恢复

### 重置前端状态

```cmd
# 清除node_modules和重新安装
rm -rf node_modules
npm install

# 或使用pnpm
rm -rf node_modules
pnpm install
```

### 重置Python环境

```cmd
# 删除嵌入式Python
rm -rf src-tauri/python-embed

# 重新设置
python scripts/setup_embedded_python.py
```

### 重置Rust构建

```cmd
# 清理Rust构建
cargo clean

# 重新构建
cargo tauri dev
```

---

通过这个故障排除指南，你应该能够解决大部分常见问题。如果遇到新问题，请按照调试步骤逐步排查。