hr-performance-system/DEPENDENCY_FIX.md

Python 依賴衝突解決方案

🔴 錯誤訊息

ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.
flask-jwt-extended 4.5.2 requires Flask<3.0,>=2.0, but you have flask 3.0.0 which is incompatible.
pyopenssl 25.3.0 requires cryptography<47,>=45.0.7, but you have cryptography 41.0.7 which is incompatible.

🔍 問題分析

這個錯誤是因為：

1. flask-jwt-extended 要求 Flask<3.0，但安裝了 Flask 3.0.0
2. pyopenssl 要求 cryptography>=45.0.7，但安裝了 cryptography 41.0.7
3. 依賴版本不相容導致衝突

✅ 解決方案

方法 1：使用修復腳本（推薦）

Windows:

fix_dependencies.bat

Linux/Mac:

chmod +x fix_dependencies.sh
./fix_dependencies.sh

方法 2：手動修復

步驟 1：清理環境

# 啟動虛擬環境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 升級 pip
python -m pip install --upgrade pip

# 解除安裝衝突的套件
pip uninstall -y Flask flask-jwt-extended pyopenssl cryptography

步驟 2：安裝相容版本

# 安裝相容的 cryptography
pip install "cryptography>=41.0.0,<47.0.0"

# 重新安裝所有依賴
pip install -r requirements.txt --upgrade

步驟 3：驗證安裝

pip list | grep -E "Flask|cryptography|PyMySQL|requests"

方法 3：使用固定版本

如果仍有問題，使用以下固定版本：

pip install Flask==2.3.3
pip install cryptography==41.0.7
pip install PyMySQL==1.1.0
pip install Flask-Cors==4.0.0
pip install requests==2.31.0
pip install python-dotenv==1.0.0

📝 更新後的 requirements.txt

已更新為使用版本範圍而非固定版本：

# Flask 核心（使用相容版本）
Flask>=2.3.0,<3.1.0
Werkzeug>=2.3.0,<3.1.0

# CORS 支援
Flask-Cors>=4.0.0

# 資料庫
PyMySQL>=1.1.0
cryptography>=41.0.0

# HTTP 請求
requests>=2.31.0

# 環境變數
python-dotenv>=1.0.0

🧪 測試安裝

安裝完成後測試：

# 測試 Python 導入
python -c "import flask; print(f'Flask version: {flask.__version__}')"
python -c "import pymysql; print('PyMySQL: OK')"
python -c "import cryptography; print(f'cryptography version: {cryptography.__version__}')"

# 啟動伺服器測試
python app.py

應該看到：

============================================================
🚀 HR Performance System API Server (Flask/Python)
============================================================
📡 Server running on: http://127.0.0.1:5002

🔧 其他解決方法

如果虛擬環境損壞

完全重建虛擬環境：

# 刪除舊的虛擬環境
# Windows:
rmdir /s /q venv

# Linux/Mac:
rm -rf venv

# 重新建立
python -m venv venv

# 啟動並安裝
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

pip install --upgrade pip
pip install -r requirements.txt

使用 pip-tools

更精確的依賴管理：

pip install pip-tools

# 編譯相容的依賴
pip-compile requirements.txt

# 安裝
pip-sync

使用 conda（可選）

如果 pip 持續有問題：

# 建立 conda 環境
conda create -n hr-system python=3.11
conda activate hr-system

# 安裝套件
conda install flask pymysql requests python-dotenv
pip install flask-cors

📋 檢查清單

修復完成後確認：

• 虛擬環境啟動成功
• pip 已升級到最新版本
• 所有依賴安裝無錯誤
• 沒有版本衝突警告
• Flask 可以正常導入
• app.py 可以啟動
• 伺服器運行在 127.0.0.1:5002
• 訪問 http://127.0.0.1:5002/health 正常

🐛 常見問題

Q1: 仍然有 cryptography 版本衝突

A: 嘗試：

pip install --upgrade cryptography

Q2: pip 安裝很慢

A: 使用國內鏡像（中國用戶）：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

Q3: 權限錯誤

A: Windows 使用管理員權限運行 PowerShell，或：

pip install --user -r requirements.txt

Q4: 找不到 Python

A: 確認 Python 在 PATH 中：

# Windows:
where python

# Linux/Mac:
which python3

📚 相關資源

• Flask 文件
• PyMySQL 文件
• pip 依賴解決

---

最後更新: 2025-12-03 適用版本: Python 3.8+