11 KiB

Raw Permalink Blame History

环境配置与依赖说明

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

📋 目录

系统要求
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 版本要求

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

Python 安装建议

官方安装器 (推荐)

# 下载 Python 3.11.7 from python.org
# 安装时勾选 "Add Python to PATH"
# 安装时勾选 "Install for all users"

通过 Microsoft Store (简单)

# 搜索 "Python 3.11" 并安装
# 自动配置环境变量

通过 pyenv-win (高级用户)

# 安装 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 安装

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

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

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

📦 依赖包详解

核心依赖

PyQt5 (5.15.11)

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

功能说明:

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

安装命令:

# 标准安装
pip install PyQt5==5.15.11

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

pyqt5-qt5 (5.15.2)

用途: Qt5 运行时库
重要性: 核心依赖
安装大小: ~100MB
许可证: LGPL v3

重要说明: ⚠️ 版本锁定原因:

Windows 平台必须使用 5.15.2 版本
更新的 5.15.17 版本不提供 Windows wheel 文件
这是 PyQt5 在 Windows 平台的已知限制

安装命令:

# 必须指定确切版本
pip install pyqt5-qt5==5.15.2

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

pywin32 (311)

用途: Windows API 访问库
重要性: 核心依赖
安装大小: ~10MB
许可证: PSF License

功能说明:

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

安装命令:

pip install pywin32==311

开发依赖

PyInstaller (6.16.0+)

用途: Python 程序打包工具
重要性: 打包依赖
安装大小: ~15MB
许可证: GPL v2

功能说明:

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

安装命令:

# 开发环境安装
uv add --dev pyinstaller>=6.0.0

依赖关系图

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 倍。

# 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

# 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

# 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 (仅用于开发，不能运行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

解决方案:

# 方案 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

解决方案:

# 强制安装兼容版本
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

解决方案:

# 方案 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 中执行（管理员权限）
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

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

问题 5: 中文路径问题

错误信息:

UnicodeDecodeError: 'gbk' codec can't decode byte

解决方案:

# 方案 A: 设置环境变量
set PYTHONIOENCODING=utf-8

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

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

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

现象:

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

解决方案:

# 1. 添加到防火墙例外
# Windows Defender 防火墙 -> 允许应用通过防火墙

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

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

📚 依赖管理最佳实践

版本锁定策略

精确版本锁定 (推荐用于生产)

PyQt5==5.15.11
pyqt5-qt5==5.15.2
pywin32==311

兼容版本范围 (用于开发)

PyQt5>=5.15.10,<5.16.0
pyqt5-qt5>=5.15.2,<5.16.0
pywin32>=311

主版本锁定 (用于扩展性)

PyQt5~=5.15.11  # 等同于 >=5.15.11, <5.16.0

requirements.txt 管理

创建多个需求文件：

# 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

依赖安全检查

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

# 使用 safety 检查
pip install safety
safety check

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

依赖更新策略

# 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. 逐步更新（推荐）
# 一次只更新一个包，测试后再更新下一个

环境隔离最佳实践

项目级隔离

# 每个项目使用独立的虚拟环境
python -m venv .venv-keypressremark

功能级隔离

# 开发环境
python -m venv .venv-dev

# 测试环境
python -m venv .venv-test

# 打包环境
python -m venv .venv-build

版本级隔离

# Python 3.11 环境
python3.11 -m venv .venv-py311

# Python 3.12 测试环境
python3.12 -m venv .venv-py312

🆘 获取支持

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

查看 Issues: GitHub Issues
提交问题: 使用问题模板提供详细信息
社区讨论: GitHub Discussions

提交问题时，请包含以下信息：

操作系统版本
Python 版本
完整的错误信息
尝试的解决方案
环境信息 (pip list 输出)

11 KiB Raw Permalink Blame History Unescape Escape

环境配置与依赖说明

📋 目录

🖥️ 系统要求

操作系统支持

硬件要求

权限要求

🐍 Python 环境

Python 版本要求

Python 安装建议

验证 Python 安装

📦 依赖包详解

核心依赖

PyQt5 (5.15.11)

pyqt5-qt5 (5.15.2)

pywin32 (311)

开发依赖

PyInstaller (6.16.0+)

依赖关系图

🔧 环境配置步骤

方案一：使用 uv (推荐)

方案二：使用传统 pip

方案三：使用 conda/mamba

Docker 环境 (实验性)

🔍 常见问题解决

问题 1: PyQt5 安装失败

问题 2: pyqt5-qt5 版本冲突

问题 3: pywin32 权限问题

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

问题 5: 中文路径问题

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

📚 依赖管理最佳实践

版本锁定策略

requirements.txt 管理

依赖安全检查

依赖更新策略

环境隔离最佳实践

🆘 获取支持

11 KiB

Raw Permalink Blame History