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. 前端调试

// 在浏览器控制台中测试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代码中添加调试信息：

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

3. Python环境调试

# 检查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官方文档
   • 相关库的文档

🔄 重置和恢复

重置前端状态

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

# 或使用pnpm
rm -rf node_modules
pnpm install

重置Python环境

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

# 重新设置
python scripts/setup_embedded_python.py

重置Rust构建

# 清理Rust构建
cargo clean

# 重新构建
cargo tauri dev

---

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