GitHub Pages 部署教程¶

说明¶

目的：为参与者提供GitHub Pages的详细部署指南
适用场景：静态网站部署，已有GitHub账号的参与者
难度：⭐⭐⭐ 中等
预计时间：30-60分钟
特点：完全免费，与GitHub集成，适合静态网站

什么是GitHub Pages？¶

基本介绍¶

服务商：GitHub (Microsoft)
产品定位：免费的静态网站托管服务
核心优势：
✅ 完全免费
✅ 与GitHub仓库集成
✅ 支持自定义域名
✅ 版本控制集成
✅ 自动部署（推送代码即部署）

适用场景¶

静态网站：HTML、CSS、JavaScript
Jekyll网站：支持Jekyll静态网站生成器
文档网站：适合文档类网站
个人作品集：适合个人作品展示
项目展示：适合项目展示页面

限制说明¶

⚠️ 仅支持静态网站：不支持服务器端代码（PHP、Python等）
⚠️ 需要翻墙：国内访问需要翻墙
⚠️ 访问速度：国内访问速度可能较慢

部署前准备¶

1. GitHub账号准备¶

1.1 注册GitHub账号¶

访问GitHub官网
网址：https://github.com
点击"Sign up"
填写注册信息
用户名
邮箱
密码
验证码验证
验证邮箱
查收验证邮件
点击验证链接
完成账号验证

1.2 安装Git（如需要）¶

下载Git
Windows：https://git-scm.com/download/win
Mac：https://git-scm.com/download/mac
Linux：使用包管理器安装
安装Git
按照安装向导完成安装
验证安装：git --version

配置Git

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

2. 项目准备¶

2.1 准备静态网站文件¶

HTML文件：准备好HTML文件
CSS文件：准备好样式文件
JavaScript文件：准备好脚本文件
资源文件：图片、字体等资源文件

2.2 项目结构示例¶

my-project/
├── index.html          # 主页面（必需）
├── css/
│   └── style.css       # 样式文件
├── js/
│   └── main.js         # JavaScript文件
├── images/
│   └── logo.png        # 图片资源
└── README.md           # 项目说明（可选）

2.3 注意事项¶

index.html必需：必须有index.html作为首页
文件路径：使用相对路径，不要使用绝对路径
文件大小：单个文件不超过100MB
仓库大小：仓库总大小不超过1GB

部署步骤（详细）¶

方法1：通过GitHub网页部署（最简单）¶

步骤1：创建新仓库¶

登录GitHub
访问 https://github.com
使用账号登录
创建新仓库
点击右上角"+" → "New repository"
填写仓库信息：
- Repository name：输入仓库名称（例如：my-website）
- Description：输入描述（可选）
- Public / Private：选择Public（GitHub Pages需要Public仓库）
- 不要勾选"Initialize this repository with a README"
点击"Create repository"

步骤2：上传文件¶

准备文件
整理好HTML文件和资源文件
确保有index.html文件
上传文件
在仓库页面，点击"uploading an existing file"
拖拽文件到上传区域
或点击"choose your files"选择文件
填写提交信息（例如：Initial commit）
点击"Commit changes"

步骤3：启用GitHub Pages¶

进入仓库设置
点击仓库页面的"Settings"
在左侧菜单找到"Pages"
配置Pages
Source：选择"Deploy from a branch"
Branch：选择"main"（或"master"）
Folder：选择"/ (root)"
点击"Save"
等待部署
等待几分钟让GitHub部署
部署完成后会显示访问链接
链接格式：https://username.github.io/repository-name

步骤4：访问网站¶

获得访问链接
在Settings → Pages页面查看链接
或访问：https://username.github.io/repository-name
验证部署
在浏览器中打开链接
确认内容正确显示
测试所有功能

方法2：通过Git命令行部署（推荐，适合有Git经验的用户）¶

步骤1：初始化Git仓库¶

打开终端/命令行
Windows：PowerShell 或 CMD
Mac：Terminal
Linux：Terminal
进入项目目录
```
cd /path/to/your/project
```
初始化Git仓库
```
git init
```

步骤2：添加文件¶

添加所有文件
```
git add .
```
提交文件
```
git commit -m "Initial commit"
```

步骤3：连接GitHub仓库¶

创建GitHub仓库（如未创建）
在GitHub上创建新仓库
不要初始化README

添加远程仓库

git remote add origin https://github.com/username/repository-name.git

推送到GitHub

git branch -M main
git push -u origin main

步骤4：启用GitHub Pages¶

在GitHub上启用Pages
进入仓库Settings → Pages
Source选择"Deploy from a branch"
Branch选择"main"
Folder选择"/ (root)"
点击"Save"
等待部署
等待几分钟让GitHub部署
部署完成后访问链接

步骤5：更新网站¶

修改文件
在本地修改文件

提交更改

git add .
git commit -m "Update website"
git push

自动部署
GitHub会自动重新部署
等待几分钟后访问更新后的网站

方法3：使用GitHub Desktop（图形界面，适合新手）¶

步骤1：安装GitHub Desktop¶

下载GitHub Desktop
网址：https://desktop.github.com
下载对应系统的版本
安装GitHub Desktop
按照安装向导完成安装
登录GitHub账号

步骤2：创建仓库¶

在GitHub Desktop中创建仓库
点击"File" → "New repository"
填写仓库信息
选择本地路径
点击"Create repository"

步骤3：添加文件¶

准备文件
在本地项目文件夹中准备文件
确保有index.html
在GitHub Desktop中添加文件
文件会自动显示在GitHub Desktop中
填写提交信息
点击"Commit to main"

步骤4：推送到GitHub¶

推送文件
点击"Push origin"
等待推送完成

步骤5：启用GitHub Pages¶

在GitHub网页上启用Pages
访问仓库页面
Settings → Pages
配置Pages设置
保存

部署后管理¶

1. 更新网站¶

方法1：通过GitHub网页更新¶

编辑文件
在GitHub仓库页面点击文件
点击"Edit"按钮
修改内容
填写提交信息
点击"Commit changes"
自动部署
GitHub会自动重新部署
等待几分钟后访问更新后的网站

方法2：通过Git命令行更新¶

git add .
git commit -m "Update website"
git push

方法3：通过GitHub Desktop更新¶

修改文件
在GitHub Desktop中提交
推送到GitHub

2. 自定义域名（可选）¶

步骤1：购买域名¶

在域名注册商购买域名
记录域名信息

步骤2：配置DNS¶

添加CNAME记录
在域名DNS设置中添加CNAME记录
名称：@ 或 www
值：username.github.io

步骤3：在GitHub Pages中配置¶

添加自定义域名
在Settings → Pages中
在"Custom domain"中输入域名
点击"Save"
等待生效
等待DNS生效（通常几分钟到几小时）
验证域名访问

3. 使用Jekyll（可选）¶

什么是Jekyll？¶

Jekyll：静态网站生成器
优势：支持Markdown、模板、插件等
适用场景：博客、文档网站等

如何使用Jekyll？¶

创建Jekyll网站
使用Jekyll模板
或从头创建
推送到GitHub
将Jekyll网站推送到GitHub仓库
自动构建
GitHub Pages会自动构建Jekyll网站
无需额外配置

常见问题解决¶

问题1：404错误¶

可能原因¶

index.html文件不存在
文件路径错误
部署未完成

解决方法¶

检查index.html
确保有index.html文件
确保文件在根目录
检查文件路径
使用相对路径
检查路径是否正确
等待部署
等待几分钟让GitHub部署
清除浏览器缓存

问题2：样式或脚本不加载¶

可能原因¶

文件路径错误
文件未上传
缓存问题

解决方法¶

检查文件路径
使用相对路径
检查路径是否正确
检查文件
确认所有文件都已上传
检查文件内容
清除缓存
清除浏览器缓存
使用无痕模式访问

问题3：国内无法访问¶

可能原因¶

GitHub Pages需要翻墙
DNS解析问题

解决方法¶

使用翻墙工具
使用VPN或代理
配置代理设置
使用CDN加速（如需要）
使用CDN服务加速访问
或使用其他部署平台

问题4：更新不生效¶

可能原因¶

缓存问题
部署未完成
文件未提交

解决方法¶

清除缓存
清除浏览器缓存
使用无痕模式访问
检查部署状态
在Settings → Pages查看部署状态
等待部署完成
检查文件
确认文件已提交
检查提交历史

最佳实践¶

1. 项目结构¶

清晰的目录结构：组织好文件结构
命名规范：使用有意义的文件名
README文件：添加README说明项目

2. 代码优化¶

代码压缩：压缩HTML、CSS、JavaScript
图片优化：优化图片大小
性能优化：提高加载速度

3. 版本控制¶

使用Git：使用Git管理代码
提交信息：写清晰的提交信息
分支管理：使用分支管理不同版本

4. 文档维护¶

README：维护README文档
注释：添加代码注释
更新日志：记录更新内容

与其他平台对比¶

GitHub Pages vs Vercel¶

特性	GitHub Pages	Vercel
免费额度	✅ 完全免费	✅ 有免费额度
部署难度	⭐⭐⭐ 中等	⭐⭐⭐⭐⭐ 最简单
国内可用性	⚠️ 需翻墙	⚠️ 需翻墙
访问速度	⭐⭐⭐ 一般	⭐⭐⭐ 一般
适用场景	静态网站	静态+动态网站
版本控制	✅ 集成Git	✅ 集成Git

GitHub Pages vs EdgeOne Pages¶

特性	GitHub Pages	EdgeOne Pages
免费额度	✅ 完全免费	需查看
部署难度	⭐⭐⭐ 中等	⭐⭐⭐ 简单
国内可用性	⚠️ 需翻墙	✅ 可用
访问速度	⭐⭐⭐ 一般	⭐⭐⭐⭐⭐ 快
适用场景	静态网站	静态网站
版本控制	✅ 集成Git	⚠️ 需手动管理

GitHub Pages 部署教程¶

说明¶

什么是GitHub Pages？¶

基本介绍¶

适用场景¶

限制说明¶

部署前准备¶

1. GitHub账号准备¶

1.1 注册GitHub账号¶

1.2 安装Git（如需要）¶

2. 项目准备¶

2.1 准备静态网站文件¶

2.2 项目结构示例¶

2.3 注意事项¶

部署步骤（详细）¶

方法1：通过GitHub网页部署（最简单）¶

步骤1：创建新仓库¶

步骤2：上传文件¶

步骤3：启用GitHub Pages¶

步骤4：访问网站¶

方法2：通过Git命令行部署（推荐，适合有Git经验的用户）¶

步骤1：初始化Git仓库¶

步骤2：添加文件¶

步骤3：连接GitHub仓库¶

步骤4：启用GitHub Pages¶

步骤5：更新网站¶

方法3：使用GitHub Desktop（图形界面，适合新手）¶

步骤1：安装GitHub Desktop¶

步骤2：创建仓库¶

步骤3：添加文件¶

步骤4：推送到GitHub¶

步骤5：启用GitHub Pages¶

部署后管理¶

1. 更新网站¶

方法1：通过GitHub网页更新¶

方法2：通过Git命令行更新¶

方法3：通过GitHub Desktop更新¶

2. 自定义域名（可选）¶

步骤1：购买域名¶

步骤2：配置DNS¶

步骤3：在GitHub Pages中配置¶

3. 使用Jekyll（可选）¶

什么是Jekyll？¶

如何使用Jekyll？¶

常见问题解决¶

问题1：404错误¶

可能原因¶

解决方法¶

问题2：样式或脚本不加载¶

可能原因¶

解决方法¶

问题3：国内无法访问¶

可能原因¶

解决方法¶

问题4：更新不生效¶

可能原因¶

解决方法¶

最佳实践¶

1. 项目结构¶

2. 代码优化¶

3. 版本控制¶

4. 文档维护¶

与其他平台对比¶

GitHub Pages vs Vercel¶

GitHub Pages vs EdgeOne Pages¶

选择建议¶

参考资源¶

官方文档¶

相关文档¶

下一步¶

完成部署后¶

学习更多¶