# github-helper

**Repository Path**: zb_com/github-helper

## Basic Information

- **Project Name**: github-helper
- **Description**: GitHub访问助手 - 解决国内网络访问难题
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-29
- **Last Updated**: 2026-04-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# GitHub 访问助手

解决国内网络访问 GitHub 困难的问题，一键启动 Web 界面，支持打开网页、下载文件、克隆仓库。

**仓库：** https://gitee.com/zb_com/github-helper

---

## 功能

解决国内网络访问 GitHub 困难的问题，一键启动 Web 界面，支持打开网页、下载文件。

| 项目 | 要求 |
|------|------|
| **Python** | 3.6 或更高版本 |
| **操作系统** | Windows / macOS / Linux |
| **网络** | 可访问互联网（用于连接代理服务） |

### 检查 Python 是否已安装

```bash
# Windows 打开 CMD 或 PowerShell
# macOS/Linux 打开终端

python --version
# 或
python3 --version
```

如果提示 `python 不是内部命令` 或 `command not found`，说明没装 Python，继续往下看。

---

## 🔧 安装 Python（如果没有）

### Windows 系统

1. 访问 https://www.python.org/downloads/
2. 点击 **Download Python 3.12.x**（或最新版本）
3. 运行安装包
4. **重要：** 勾选 `Add Python to PATH`（添加到环境变量）
5. 点击 `Install Now`
6. 安装完成后重新打开 CMD，执行 `python --version` 验证

### macOS 系统

```bash
# 使用 Homebrew 安装
brew install python3
```

### Linux 系统

```bash
# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip

# CentOS/RHEL
sudo yum install python3
```

---

## 🚀 开始使用

### 方法一：Windows 一键启动（推荐）

1. 下载本项目所有文件到一个文件夹
2. 确保 `github_web.py` 和 `start.bat` 在同一目录
3. **双击 `start.bat`**
4. 等待浏览器自动打开 http://localhost:8080
5. 如果浏览器没有自动打开，手动打开浏览器访问上面的地址

### 方法二：命令行启动

```bash
# 进入项目目录
cd 下载目录/github-helper

# Windows
python github_web.py

# macOS / Linux
python3 github_web.py
```

然后手动打开浏览器访问 http://localhost:8080

---

## 📖 功能说明

| 功能 | 使用方法 |
|------|----------|
| 🌐 **打开网页** | 在输入框粘贴 GitHub 任意链接，点击"打开" |
| 📥 **下载文件** | 粘贴文件/资源的 URL，点击"下载"，浏览器会自动下载 |
| ⚡ **克隆准备** | 输入 `用户名/仓库名` 格式，打开仓库页面后复制克隆地址 |

### 常用链接示例

| 链接 | 说明 |
|------|------|
| https://github.com | GitHub 首页 |
| https://github.com/trending | 热门项目 |
| https://github.com/user/repo | 某个仓库 |
| https://github.com/user/repo/releases | 某仓库的所有版本 |
| https://github.com/user/repo/archive/main.zip | 下载源码压缩包 |

---

## 🔧 工作原理

程序会自动尝试多个 GitHub 代理服务：
1. ghproxy.com
2. mirror.ghproxy.com
3. gh-proxy.com

请求会通过可用的代理转发。如果所有代理都不可用，会自动 fallback 到直接访问。

---

## ⚠️ 常见问题

### Q: 提示"代理不可用"怎么办？
**A:** 
1. 检查网络是否正常
2. 点击页面上的"刷新状态"按钮重试
3. 等待几分钟后重试（可能是代理服务暂时维护）

### Q: 下载的文件是空的或损坏？
**A:** 可能是 GitHub 速率限制，请：
1. 打开 https://github.com 并登录
2. 稍后再尝试下载

### Q: 怎么停止服务？
**A:** 关闭运行程序的终端窗口，或按 `Ctrl+C`

### Q: 端口 8080 被占用了？
**A:** 
1. 修改 `github_web.py` 中的 `PORT = 8080` 为其他端口（如 8090）
2. 重启程序后用新的端口访问

### Q: 浏览器没有自动打开？
**A:** 手动打开浏览器访问 http://localhost:8080

### Q: Windows 双击 start.bat 闪退？
**A:** 
1. 右键 `start.bat` → 编辑
2. 把 `python` 改成 `python3`
3. 保存后重新双击

---

## 📁 文件说明

```
github-helper/
├── github_web.py   # Web 界面主程序（核心，跨平台）
├── start.bat       # Windows 一键启动脚本（双击运行）
└── README.md       # 本说明文档
```

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 License

MIT License