chenheng/MetaCore-startup

Fork 0

陈横 ee7a5db41c init

2025-10-11 09:24:06 +08:00

5.4 KiB

Raw Permalink Blame History

MetaCore虚拟环境完整指南

🎯 概述

为MetaCore PyQt5版本创建独立的Python虚拟环境，确保项目依赖不会与系统其他Python项目冲突。

📁 已创建的文件

自动化脚本

setup_and_run.bat - Windows一键启动脚本
setup_and_run.sh - macOS/Linux一键启动脚本
test_environment.py - 环境测试脚本

配置文件

requirements.txt - 项目依赖列表
虚拟环境设置指南.md - 详细设置说明
虚拟环境快速参考.md - 快速参考卡

🚀 快速开始

方法1：一键启动（推荐）

Windows用户

# 双击运行或命令行执行
setup_and_run.bat

macOS/Linux用户

# 首次运行需要给权限
chmod +x setup_and_run.sh

# 运行脚本
./setup_and_run.sh

方法2：手动设置

1. 创建虚拟环境

# Windows
python -m venv metacore_env

# macOS/Linux
python3 -m venv metacore_env

2. 激活虚拟环境

# Windows
metacore_env\Scripts\activate

# macOS/Linux
source metacore_env/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 运行应用

python main.py

5. 退出虚拟环境

deactivate

🔧 环境测试

运行环境测试脚本检查配置：

python test_environment.py

测试内容包括：

✅ Python版本检查
✅ PyQt5安装验证
✅ 项目文件完整性
✅ 模块导入测试
✅ 虚拟环境状态

📋 依赖包说明

必需依赖

PyQt5 >= 5.15.0 - GUI框架

可选依赖

Pillow >= 8.0.0 - 图像处理（如需要更好的图标支持）
psutil >= 5.8.0 - 系统信息（如需要系统集成功能）

🎯 使用场景

开发环境

# 激活环境
metacore_env\Scripts\activate

# 开发调试
python main.py

# 安装新依赖
pip install package_name

# 更新依赖列表
pip freeze > requirements.txt

# 退出环境
deactivate

生产环境

# 创建干净环境
python -m venv production_env

# 激活环境
production_env\Scripts\activate

# 安装指定依赖
pip install -r requirements.txt

# 运行应用
python main.py

🔍 故障排除

常见问题及解决方案

1. Python命令不存在

症状： 'python' 不是内部或外部命令 解决：

重新安装Python并勾选"Add to PATH"
或使用完整路径：C:\Python39\python.exe

2. venv模块不存在

症状： No module named venv 解决：

pip install virtualenv
virtualenv metacore_env

3. PyQt5安装失败

症状： 网络错误或编译错误 解决：

# 使用国内镜像
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt5

# 或使用conda
conda install pyqt

4. 权限错误

症状： Permission denied 解决：

Windows：以管理员身份运行
macOS/Linux：检查目录权限 chmod 755 /path/to/MetaCore

5. 虚拟环境激活失败

症状： 激活脚本不存在 解决：

# 删除并重新创建
rm -rf metacore_env
python -m venv metacore_env

📊 环境管理最佳实践

1. 项目隔离

每个项目使用独立的虚拟环境
避免在系统Python中安装项目依赖

2. 依赖管理

使用requirements.txt记录依赖
定期更新依赖包版本
区分开发依赖和生产依赖

3. 版本控制

将虚拟环境目录添加到.gitignore
只提交requirements.txt文件
在不同环境中重新创建虚拟环境

4. 文档维护

记录环境创建步骤
说明特殊依赖的安装方法
提供故障排除指南

🎨 目录结构

完整的项目目录结构：

MetaCore/
├── metacore_env/                 # 虚拟环境（不提交到版本控制）
│   ├── Scripts/                 # Windows
│   ├── bin/                     # macOS/Linux
│   ├── lib/
│   └── pyvenv.cfg
├── data/                        # 数据模块
├── ui/                          # 界面模块
├── main.py                      # 主程序
├── requirements.txt             # 依赖列表
├── setup_and_run.bat           # Windows启动脚本
├── setup_and_run.sh            # macOS/Linux启动脚本
├── test_environment.py         # 环境测试脚本
├── 虚拟环境设置指南.md         # 详细指南
├── 虚拟环境快速参考.md         # 快速参考
└── 虚拟环境完整指南.md         # 本文档

🚀 部署建议

开发部署

克隆项目代码
创建虚拟环境
安装依赖包
运行测试脚本
启动应用

生产部署

使用干净的Python环境
创建专用虚拟环境
安装精确版本的依赖
配置系统服务
设置日志和监控

📞 获取帮助

自助诊断

运行 python test_environment.py 检查环境
查看 虚拟环境快速参考.md 获取常用命令
参考 虚拟环境设置指南.md 获取详细说明

常用检查命令

# 检查Python版本
python --version

# 检查虚拟环境状态
echo $VIRTUAL_ENV          # Linux/macOS
echo %VIRTUAL_ENV%         # Windows

# 检查已安装包
pip list

# 检查PyQt5
python -c "import PyQt5; print('PyQt5可用')"

🎉 虚拟环境配置完成！

现在您可以在独立的环境中安全地运行MetaCore PyQt5版本，不用担心依赖冲突问题。选择最适合您的启动方式，开始使用吧！

5.4 KiB Raw Permalink Blame History Unescape Escape