MetaCore-startup/虚拟环境设置指南.txt

MetaCore 虚拟环境设置指南
================================

目录
----
1. 快速开始
2. 详细步骤
3. 常用命令
4. 故障排除
5. 最佳实践

================================

1. 快速开始
----------

Windows用户：
1. 打开命令提示符(cmd)
2. 进入项目目录：cd /d D:\PythonProject\MetaCore-startup
3. 创建虚拟环境：python -m venv metacore_env
4. 激活环境：metacore_env\Scripts\activate
5. 安装依赖：pip install -r MetaCore\requirements.txt
6. 运行程序：cd MetaCore && python main.py

macOS/Linux用户：
1. 打开终端
2. 进入项目目录：cd /path/to/MetaCore-startup
3. 创建虚拟环境：python3 -m venv metacore_env
4. 激活环境：source metacore_env/bin/activate
5. 安装依赖：pip install -r MetaCore/requirements.txt
6. 运行程序：cd MetaCore && python main.py

================================

2. 详细步骤
----------

步骤1：检查Python环境
- 确保Python 3.7+已安装
- 检查命令：python --version 或 python3 --version

步骤2：创建虚拟环境
Windows：
  python -m venv metacore_env

macOS/Linux：
  python3 -m venv metacore_env

步骤3：激活虚拟环境
Windows：
  metacore_env\Scripts\activate

macOS/Linux：
  source metacore_env/bin/activate

激活成功后，命令提示符前会显示 (metacore_env)

步骤4：升级pip（推荐）
  python -m pip install --upgrade pip

步骤5：安装项目依赖
  pip install -r MetaCore\requirements.txt

主要依赖包：
- PyQt5 >= 5.15.0 (GUI框架，必需)
- PyInstaller >= 5.0.0 (打包工具，必需)
- Pillow >= 8.0.0 (图像处理，推荐)
- psutil >= 5.8.0 (系统信息，可选)

标准库模块（无需安装）：
- sys, os, json, datetime (系统和文件操作)
- pathlib (路径处理)
- subprocess (进程管理)
- platform (平台信息)
- typing (类型提示)

步骤6：验证安装
  python -c "import PyQt5; print('PyQt5安装成功')"

步骤7：运行应用
  cd MetaCore
  python main.py

步骤8：退出虚拟环境
  deactivate

================================

3. 常用命令
----------

环境管理：
- 创建环境：python -m venv 环境名
- 激活环境：
  Windows: 环境名\Scripts\activate
  Linux/Mac: source 环境名/bin/activate
- 退出环境：deactivate
- 删除环境：直接删除环境文件夹

包管理：
- 安装包：pip install 包名
- 安装指定版本：pip install 包名==版本号
- 安装需求文件：pip install -r requirements.txt
- 查看已安装包：pip list
- 查看包信息：pip show 包名
- 卸载包：pip uninstall 包名
- 导出需求文件：pip freeze > requirements.txt

环境检查：
- 检查Python版本：python --version
- 检查pip版本：pip --version
- 检查虚拟环境：echo $VIRTUAL_ENV (Linux/Mac)
                echo %VIRTUAL_ENV% (Windows)
- 检查PyQt5：python -c "import PyQt5; print('可用')"

================================

4. 故障排除
----------

问题1：python命令不存在
解决：
- 重新安装Python，勾选"Add Python to PATH"
- 或使用完整路径：C:\Python39\python.exe

问题2：venv模块不存在
解决：
- pip install virtualenv
- 使用：virtualenv metacore_env

问题3：PyQt5安装失败
解决：
- 使用国内镜像：
  pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyQt5
- 或使用清华镜像：
  pip install -i https://pypi.mirrors.ustc.edu.cn/simple/ PyQt5
- 或使用阿里云镜像：
  pip install -i https://mirrors.aliyun.com/pypi/simple/ PyQt5

问题3.1：PyInstaller安装失败
解决：
- 使用国内镜像：
  pip install -i https://pypi.tuna.tsinghua.edu.cn/simple PyInstaller
- 或直接安装：
  pip install PyInstaller

问题3.2：Pillow安装失败
解决：
- 使用国内镜像：
  pip install -i https://pypi.tuna.tsinghua.edu.cn/simple Pillow
- 或使用预编译版本：
  pip install --upgrade Pillow

问题4：权限错误
解决：
- Windows：以管理员身份运行命令提示符
- Linux/Mac：使用sudo或检查目录权限

问题5：激活脚本不存在
解决：
- 删除环境文件夹，重新创建
- 检查Python版本是否支持venv模块

问题6：导入PyQt5失败
解决：
- 确认在虚拟环境中安装：pip list | grep PyQt5
- 重新安装：pip uninstall PyQt5 && pip install PyQt5
- 检查Python版本兼容性：PyQt5需要Python 3.7+

问题7：依赖包版本冲突
解决：
- 查看冲突信息：pip check
- 升级pip：python -m pip install --upgrade pip
- 清理缓存：pip cache purge
- 重新安装：pip install --force-reinstall -r MetaCore\requirements.txt

问题8：网络连接问题
解决：
- 使用国内镜像源（推荐清华源）：
  pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
- 或临时使用镜像：
  pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r MetaCore\requirements.txt

================================

5. 最佳实践
----------

项目隔离：
- 每个项目使用独立的虚拟环境
- 不在系统Python中安装项目依赖
- 虚拟环境命名要有意义

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

版本控制：
- 将虚拟环境目录添加到.gitignore
- 只提交requirements.txt文件
- 在不同机器上重新创建虚拟环境

目录结构：
MetaCore-startup/
├── metacore_env/          # 虚拟环境（不提交版本控制）
├── MetaCore/              # 主程序目录
│   ├── main.py           # 程序入口
│   ├── requirements.txt  # 依赖列表
│   └── ...
├── Doc/                   # 文档目录
├── tests/                 # 测试目录
└── README.md             # 项目说明

环境变量：
- 激活环境后，VIRTUAL_ENV变量指向环境路径
- PATH变量会优先使用虚拟环境中的Python和pip

安全建议：
- 定期更新pip：python -m pip install --upgrade pip
- 使用固定版本号避免依赖冲突
- 在生产环境中使用requirements.txt精确安装

================================

快速参考卡
----------

创建并激活环境：
Windows:
  python -m venv metacore_env
  metacore_env\Scripts\activate

Linux/Mac:
  python3 -m venv metacore_env
  source metacore_env/bin/activate

安装依赖并运行：
  pip install -r MetaCore\requirements.txt
  cd MetaCore
  python main.py

退出环境：
  deactivate

================================

联系方式
--------
如遇到问题，请：
1. 先运行 python MetaCore\验证安装.py 检查环境
2. 查看项目文档：Doc\README.md
3. 参考详细指南：Doc\虚拟环境完整指南.md

================================

完整依赖包说明
--------------

必需依赖（必须安装）：
1. PyQt5 >= 5.15.0
   - 作用：GUI框架，提供窗口、按钮、对话框等界面组件
   - 安装：pip install PyQt5
   - 验证：python -c "import PyQt5; print('PyQt5可用')"

2. PyInstaller >= 5.0.0
   - 作用：将Python程序打包成可执行文件
   - 安装：pip install PyInstaller
   - 验证：pyinstaller --version

推荐依赖（建议安装）：
3. Pillow >= 8.0.0
   - 作用：图像处理库，提供更好的图标和图片支持
   - 安装：pip install Pillow
   - 验证：python -c "import PIL; print('Pillow可用')"

可选依赖（按需安装）：
4. psutil >= 5.8.0
   - 作用：系统信息库，提供系统集成功能
   - 安装：pip install psutil
   - 验证：python -c "import psutil; print('psutil可用')"

标准库模块（Python内置，无需安装）：
- sys：系统相关功能
- os：操作系统接口
- json：JSON数据处理
- datetime：日期时间处理
- pathlib：路径操作
- subprocess：子进程管理
- platform：平台信息
- typing：类型提示

一键安装所有依赖：
pip install PyQt5 PyInstaller Pillow psutil

或使用requirements.txt：
pip install -r MetaCore\requirements.txt

================================

祝您使用愉快！