fix

docs/TROUBLESHOOTING_PYTHON_ENV.md

@@ -0,0 +1,245 @@
+# 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
+```
+
+---
+
+通过这个故障排除指南，你应该能够解决大部分常见问题。如果遇到新问题，请按照调试步骤逐步排查。