增加跨平台兼容性

2026-02-14 01:38:29 +08:00
parent e20c435e43
commit 19a94c45bb
6 changed files with 579 additions and 6 deletions
--- a/跨平台说明.md
+++ b/跨平台说明.md
@@ -0,0 +1,150 @@
+# 跨平台兼容性说明
+
+QuickGit 现已完全支持 **Windows**、**Linux** 和 **macOS** 三大平台！
+
+## 快速开始
+
+### Windows
+```bash
+# 方式1：使用启动脚本（推荐）
+run.bat
+
+# 方式2：直接运行
+python quickgit.py
+```
+
+### Linux/macOS
+```bash
+# 首次使用：添加执行权限
+chmod +x run.sh
+
+# 方式1：使用启动脚本（推荐）
+./run.sh
+
+# 方式2：直接运行
+python3 quickgit.py
+```
+
+## 平台特定功能
+
+### 自动编码配置
+- **Windows:** `run.bat` 自动设置 UTF-8 编码 (`chcp 65001`)
+- **Linux/macOS:** `run.sh` 设置 `LANG` 和 `LC_ALL` 环境变量
+
+### 跨平台工具类 (PlatformUtils)
+
+新增 `PlatformUtils` 类提供跨平台支持：
+
+```python
+from quickgit.utils import PlatformUtils
+
+# 清屏（自动适配平台）
+PlatformUtils.clear_screen()
+
+# 平台检测
+if PlatformUtils.is_windows():
+    print("Running on Windows")
+elif PlatformUtils.is_linux():
+    print("Running on Linux")
+elif PlatformUtils.is_mac():
+    print("Running on macOS")
+
+# 获取平台名称
+platform = PlatformUtils.get_platform_name()  # "Windows", "Linux", "macOS"
+```
+
+## 测试清单
+
+在 Linux/macOS 上测试时，请验证以下功能：
+
+- [ ] 启动脚本 `./run.sh` 正常运行
+- [ ] 彩色输出正确显示
+- [ ] 中文字符正常显示（UTF-8编码）
+- [ ] Git 初始化功能正常
+- [ ] Git 提交推送功能正常
+- [ ] Git 拉取功能正常
+- [ ] 远程仓库管理功能正常
+- [ ] 所有 ASCII 边框对齐（60字符宽）
+- [ ] 状态指示器 `[√]`, `[×]`, `[i]`, `[!]`, `[>]` 正常显示
+
+## 已验证的兼容性
+
+### Python 版本
+- ✅ Python 3.6+
+- ✅ Python 3.10+ (type hints: `list[str]`, `tuple[bool, str]`)
+
+### 操作系统
+- ✅ Windows 10/11
+- ✅ Linux (Ubuntu, Debian, Fedora, Arch, etc.)
+- ✅ macOS 10.15+
+
+### 终端
+- ✅ Windows Terminal
+- ✅ PowerShell
+- ✅ CMD (Windows 10+)
+- ✅ Bash
+- ✅ Zsh
+- ✅ Fish
+
+## 注意事项
+
+1. **Python 命令差异:**
+   - Windows: `python`
+   - Linux/macOS: `python3`
+
+2. **脚本权限:**
+   - Linux/macOS 首次使用需要: `chmod +x run.sh`
+
+3. **编码要求:**
+   - 终端必须支持 UTF-8 编码
+   - 使用启动脚本可自动配置
+
+4. **颜色支持:**
+   - 现代终端均支持 ANSI 颜色代码
+   - Windows 10+ 原生支持
+   - 旧版 Windows 可能需要启用虚拟终端
+
+## 故障排查
+
+### 问题：中文乱码
+**解决:**
+```bash
+# Linux/macOS
+export LANG=zh_CN.UTF-8
+export LC_ALL=zh_CN.UTF-8
+
+# Windows
+chcp 65001
+```
+
+### 问题：颜色不显示
+**检查:**
+- 终端是否支持 ANSI 颜色
+- Windows: 使用 Windows Terminal 或 PowerShell
+
+### 问题：run.sh 没有执行权限
+**解决:**
+```bash
+chmod +x run.sh
+```
+
+### 问题：python3 命令不存在
+**解决:**
+```bash
+# 创建软链接
+sudo ln -s /usr/bin/python3 /usr/bin/python
+
+# 或安装 Python 3
+# Ubuntu/Debian:
+sudo apt install python3
+
+# Fedora:
+sudo dnf install python3
+
+# macOS (使用 Homebrew):
+brew install python3
+```
+
+## 贡献
+
+如果您在特定平台上发现兼容性问题，欢迎提交 Issue 或 Pull Request！