KeyPress/docs/ENVIRONMENT_SETUP.md

# 环境配置与依赖说明

本文档详细说明了 KeyPressRemark 项目的环境配置要求、依赖管理和常见问题解决方案。

## 📋 目录

- [系统要求](#系统要求)
- [Python 环境](#python-环境)
- [依赖包详解](#依赖包详解)
- [环境配置步骤](#环境配置步骤)
- [常见问题解决](#常见问题解决)
- [依赖管理最佳实践](#依赖管理最佳实践)

## 🖥️ 系统要求

### 操作系统支持

| 操作系统 | 版本要求 | 支持状态 | 说明 |
|---------|---------|---------|------|
| Windows 10 | 1909+ | ✅ 完全支持 | 推荐版本 |
| Windows 11 | 所有版本 | ✅ 完全支持 | 推荐版本 |
| Windows 8.1 | 所有版本 | ⚠️ 基本支持 | 部分功能可能受限 |
| Windows 7 | SP1+ | ❌ 不支持 | PyQt5 不再支持 |
| Linux | 任何发行版 | ❌ 不支持 | Windows API 依赖 |
| macOS | 任何版本 | ❌ 不支持 | Windows API 依赖 |

### 硬件要求

| 组件 | 最低要求 | 推荐配置 |
|------|---------|---------|
| CPU | 1GHz 单核 | 2GHz 双核+ |
| 内存 | 512MB | 2GB+ |
| 硬盘 | 100MB 可用空间 | 500MB+ |
| 显示器 | 800x600 | 1920x1080+ |

### 权限要求

- **管理员权限**: 必需（用于按键模拟功能）
- **UAC 设置**: 建议设置为最低级别，减少弹窗干扰
- **防火墙**: 无特殊要求
- **杀毒软件**: 可能需要将程序添加到白名单

## 🐍 Python 环境

### Python 版本要求

```yaml
最低版本: Python 3.11.0
推荐版本: Python 3.11.7+
测试版本: 
  - Python 3.11.7 ✅
  - Python 3.12.x ✅
  - Python 3.10.x ⚠️ (可能存在兼容性问题)
```

### Python 安装建议

1. **官方安装器** (推荐)
   ```bash
   # 下载 Python 3.11.7 from python.org
   # 安装时勾选 "Add Python to PATH"
   # 安装时勾选 "Install for all users"
   ```

2. **通过 Microsoft Store** (简单)
   ```bash
   # 搜索 "Python 3.11" 并安装
   # 自动配置环境变量
   ```

3. **通过 pyenv-win** (高级用户)
   ```bash
   # 安装 pyenv-win
   git clone https://github.com/pyenv-win/pyenv-win.git %USERPROFILE%\.pyenv
   
   # 安装指定版本
   pyenv install 3.11.7
   pyenv global 3.11.7
   ```

### 验证 Python 安装

```bash
# 检查 Python 版本
python --version
# 输出: Python 3.11.7

# 检查 pip 版本
pip --version
# 输出: pip 23.3.1 from ...

# 检查环境变量
echo %PATH%
# 应该包含 Python 安装路径
```

## 📦 依赖包详解

### 核心依赖

#### PyQt5 (5.15.11)
```yaml
用途: 图形用户界面框架
重要性: 核心依赖
安装大小: ~50MB
许可证: GPL v3 / Commercial
```

**功能说明**:
- 提供完整的 GUI 组件库
- 支持信号槽机制
- 跨平台支持（本项目仅用于 Windows）
- 事件循环和定时器功能

**安装命令**:
```bash
# 标准安装
pip install PyQt5==5.15.11

# 使用 uv (推荐)
uv pip install PyQt5==5.15.11
```

#### pyqt5-qt5 (5.15.2)
```yaml
用途: Qt5 运行时库
重要性: 核心依赖
安装大小: ~100MB
许可证: LGPL v3
```

**重要说明**:
⚠️ **版本锁定原因**: 
- Windows 平台必须使用 `5.15.2` 版本
- 更新的 `5.15.17` 版本不提供 Windows wheel 文件
- 这是 PyQt5 在 Windows 平台的已知限制

**安装命令**:
```bash
# 必须指定确切版本
pip install pyqt5-qt5==5.15.2

# 使用 uv
uv pip install pyqt5-qt5==5.15.2
```

#### pywin32 (311)
```yaml
用途: Windows API 访问库
重要性: 核心依赖
安装大小: ~10MB
许可证: PSF License
```

**功能说明**:
- 提供 Python 访问 Windows API 的能力
- 包含 win32gui, win32api, win32con 等模块
- 支持窗口操作、消息发送、系统信息获取
- 版本号与 Windows 构建号相关

**安装命令**:
```bash
pip install pywin32==311
```

### 开发依赖

#### PyInstaller (6.16.0+)
```yaml
用途: Python 程序打包工具
重要性: 打包依赖
安装大小: ~15MB
许可证: GPL v2
```

**功能说明**:
- 将 Python 程序打包为独立的可执行文件
- 支持单文件和目录两种打包方式
- 自动处理依赖关系
- 支持自定义图标和版本信息

**安装命令**:
```bash
# 开发环境安装
uv add --dev pyinstaller>=6.0.0
```

### 依赖关系图

```mermaid
graph TD
    A[KeyPressRemark] --> B[PyQt5]
    A --> C[pywin32]
    B --> D[pyqt5-qt5]
    B --> E[pyqt5-sip]
    
    A --> F[PyInstaller] 
    F --> G[altgraph]
    F --> H[pefile]
    F --> I[pyinstaller-hooks-contrib]
    
    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#f3e5f5
    style D fill:#fff3e0
    style F fill:#e8f5e8
```

## 🔧 环境配置步骤

### 方案一：使用 uv (推荐)

uv 是新一代 Python 包管理器，速度比 pip 快 10-100 倍。

```bash
# 1. 安装 uv
pip install uv

# 2. 克隆项目
git clone <repository-url>
cd KeyPressRemark

# 3. 创建虚拟环境
uv venv --python 3.11

# 4. 激活虚拟环境
.venv\Scripts\activate

# 5. 安装依赖
uv pip install PyQt5==5.15.11 pyqt5-qt5==5.15.2 pywin32==311

# 6. 安装开发依赖（可选）
uv add --dev pyinstaller pytest pytest-qt black isort flake8

# 7. 验证安装
python -c "import PyQt5; print('PyQt5 安装成功')"
python -c "import win32gui; print('pywin32 安装成功')"
```

### 方案二：使用传统 pip

```bash
# 1. 克隆项目
git clone <repository-url>
cd KeyPressRemark

# 2. 创建虚拟环境
python -m venv .venv

# 3. 激活虚拟环境
.venv\Scripts\activate

# 4. 升级 pip
python -m pip install --upgrade pip

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

# 6. 验证安装
python src/main.py
```

### 方案三：使用 conda/mamba

```bash
# 1. 创建 conda 环境
conda create -n keypressremark python=3.11

# 2. 激活环境
conda activate keypressremark

# 3. 安装依赖
# 注意：PyQt5 通过 conda-forge 安装可能版本不匹配
pip install PyQt5==5.15.11 pyqt5-qt5==5.15.2 pywin32==311

# 4. 验证安装
python src/main.py
```

### Docker 环境 (实验性)

```dockerfile
# Dockerfile (仅用于开发，不能运行GUI)
FROM python:3.11-windowsservercore

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY src/ ./src/
CMD ["python", "src/main.py"]
```

注意：由于 Windows API 依赖，Docker 环境主要用于代码检查，无法运行完整功能。

## 🔍 常见问题解决

### 问题 1: PyQt5 安装失败

**错误信息**:
```
ERROR: Could not find a version that satisfies the requirement PyQt5
```

**解决方案**:
```bash
# 方案 A: 使用官方索引
pip install -i https://pypi.org/simple/ PyQt5==5.15.11

# 方案 B: 手动下载 wheel 文件
# 从 https://pypi.org/project/PyQt5/#files 下载对应版本
pip install PyQt5-5.15.11-cp311-cp311-win_amd64.whl

# 方案 C: 清理缓存重试
pip cache purge
pip install PyQt5==5.15.11
```

### 问题 2: pyqt5-qt5 版本冲突

**错误信息**:
```
Distribution pyqt5-qt5==5.15.17 can't be installed because it doesn't have a wheel for the current platform
```

**解决方案**:
```bash
# 强制安装兼容版本
uv pip install pyqt5-qt5==5.15.2 --force-reinstall

# 或者手动指定约束
echo "pyqt5-qt5==5.15.2" > constraints.txt
pip install PyQt5==5.15.11 -c constraints.txt
```

### 问题 3: pywin32 权限问题

**错误信息**:
```
Access is denied
```

**解决方案**:
```bash
# 方案 A: 管理员权限安装
# 以管理员身份运行命令提示符
pip install pywin32==311

# 方案 B: 用户级安装
pip install --user pywin32==311

# 方案 C: 安装后手动注册
python Scripts/pywin32_postinstall.py -install
```

### 问题 4: 虚拟环境激活失败

**错误信息**:
```
cannot be loaded because running scripts is disabled on this system
```

**解决方案**:
```powershell
# 在 PowerShell 中执行（管理员权限）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 然后重新激活虚拟环境
.venv\Scripts\activate
```

### 问题 5: 中文路径问题

**错误信息**:
```
UnicodeDecodeError: 'gbk' codec can't decode byte
```

**解决方案**:
```bash
# 方案 A: 设置环境变量
set PYTHONIOENCODING=utf-8

# 方案 B: 避免中文路径
# 将项目移动到英文路径下

# 方案 C: 修改系统区域设置
# 控制面板 -> 区域 -> 管理 -> 更改系统区域设置 -> Beta: 使用 Unicode UTF-8
```

### 问题 6: 防火墙/杀毒软件拦截

**现象**: 
- 程序无法启动
- 按键发送功能异常
- 弹出安全警告

**解决方案**:
```bash
# 1. 添加到防火墙例外
# Windows Defender 防火墙 -> 允许应用通过防火墙

# 2. 添加到杀毒软件白名单
# 各杀毒软件设置方法不同，需要将以下路径添加到白名单：
# - Python.exe 路径
# - 项目文件夹路径
# - 生成的 exe 文件路径

# 3. 临时关闭实时保护（仅测试用）
# Windows 安全中心 -> 病毒和威胁防护 -> 实时保护
```

## 📚 依赖管理最佳实践

### 版本锁定策略

1. **精确版本锁定** (推荐用于生产)
   ```
   PyQt5==5.15.11
   pyqt5-qt5==5.15.2
   pywin32==311
   ```

2. **兼容版本范围** (用于开发)
   ```
   PyQt5>=5.15.10,<5.16.0
   pyqt5-qt5>=5.15.2,<5.16.0
   pywin32>=311
   ```

3. **主版本锁定** (用于扩展性)
   ```
   PyQt5~=5.15.11  # 等同于 >=5.15.11, <5.16.0
   ```

### requirements.txt 管理

创建多个需求文件：

```bash
# requirements/base.txt - 基础依赖
PyQt5==5.15.11
pyqt5-qt5==5.15.2
pywin32==311

# requirements/dev.txt - 开发依赖
-r base.txt
pytest>=7.0.0
pytest-qt>=4.0.0
black>=22.0.0
isort>=5.0.0
flake8>=4.0.0

# requirements/build.txt - 打包依赖
-r base.txt
pyinstaller>=6.0.0
```

### 依赖安全检查

```bash
# 使用 pip-audit 检查安全漏洞
pip install pip-audit
pip-audit

# 使用 safety 检查
pip install safety
safety check

# 检查依赖许可证
pip install pip-licenses
pip-licenses
```

### 依赖更新策略

```bash
# 1. 检查过时的包
pip list --outdated

# 2. 生成当前环境的精确依赖
pip freeze > requirements-lock.txt

# 3. 测试更新（在独立环境中）
python -m venv test-env
test-env\Scripts\activate
pip install -r requirements.txt
python src/main.py  # 测试功能

# 4. 逐步更新（推荐）
# 一次只更新一个包，测试后再更新下一个
```

### 环境隔离最佳实践

1. **项目级隔离**
   ```bash
   # 每个项目使用独立的虚拟环境
   python -m venv .venv-keypressremark
   ```

2. **功能级隔离**
   ```bash
   # 开发环境
   python -m venv .venv-dev
   
   # 测试环境
   python -m venv .venv-test
   
   # 打包环境
   python -m venv .venv-build
   ```

3. **版本级隔离**
   ```bash
   # Python 3.11 环境
   python3.11 -m venv .venv-py311
   
   # Python 3.12 测试环境
   python3.12 -m venv .venv-py312
   ```

---

## 🆘 获取支持

如果遇到环境配置问题，可以通过以下方式获取帮助：

1. **查看 Issues**: [GitHub Issues](https://github.com/your-repo/issues)
2. **提交问题**: 使用问题模板提供详细信息
3. **社区讨论**: [GitHub Discussions](https://github.com/your-repo/discussions)

提交问题时，请包含以下信息：
- 操作系统版本
- Python 版本
- 完整的错误信息
- 尝试的解决方案
- 环境信息 (`pip list` 输出)