## 简介
GitHub Pages 是 GitHub 提供的一个静态网站托管服务，可以免费托管个人、项目或组织页面。本教程将指导您如何部署一个单页面应用到 GitHub Pages。
## 前提条件
- 拥有 GitHub 账号
- 已安装 Git
- 已安装 Node.js（如果使用前端框架）
## 部署步骤
### 1. 创建仓库
1. 登录 GitHub 账号
2. 点击右上角的 "+" 按钮，选择 "New repository"
3. 仓库名称格式为：`username.github.io`（username 替换为您的 GitHub 用户名）
4. 选择 "Public" 可见性
5. 点击 "Create repository"
### 2. 准备项目
#### 如果是普通 HTML 项目：
1. 在本地创建项目文件夹
2. 创建 `index.html` 文件
3. 添加您的网页内容
#### 如果是使用前端框架（如 React、Vue 等）：
1. 创建项目（以 React 为例）：
```bash
npx create-react-app my-app
cd my-app
```
2. 在 `package.json` 中添加 homepage 字段：
```json
{
"homepage": "https://username.github.io"
}
```
3. 安装 gh-pages 包：
```bash
npm install --save-dev gh-pages
```
4. 在 `package.json` 的 scripts 中添加部署命令：
```json
{
"scripts": {
"predeploy": "npm run build",
"deploy": "gh-pages -d build"
}
}
```
### 3. 部署项目
#### 普通 HTML 项目：
1. 初始化 Git 仓库：
```bash
git init
git add .
git commit -m "Initial commit"
```
2. 添加远程仓库：
```bash
git remote add origin https://github.com/username/username.github.io.git
```
3. 推送代码：
```bash
git push -u origin main
```
#### 前端框架项目：
1. 构建项目：
```bash
npm run build
```
2. 部署到 GitHub Pages：
```bash
npm run deploy
```
### 4. 访问网站
- 部署完成后，等待几分钟
- 访问 `https://username.github.io` 查看您的网站
## 注意事项
1. 确保仓库名称为 `username.github.io` 格式
2. 确保仓库设置为 Public
3. 如果使用自定义域名，需要在仓库设置中配置
4. 部署后可能需要等待几分钟才能访问
## 常见问题解决
1. 页面显示 404
- 检查仓库名称是否正确
- 确认文件是否在正确的分支
- 检查 index.html 是否在根目录
2. 样式或资源加载失败
- 检查资源路径是否正确
- 确保使用相对路径或完整的 GitHub Pages URL
3. 部署后更新未生效
- 清除浏览器缓存
- 确认部署命令执行成功
- 检查 GitHub Actions 状态（如果使用）
## 进阶配置
1. 自定义域名
- 在仓库设置中找到 "Pages" 选项
- 在 "Custom domain" 中输入您的域名
- 配置 DNS 记录
2. 使用 GitHub Actions 自动部署
- 创建 `.github/workflows` 目录
- 添加部署配置文件
## 总结
GitHub Pages 是一个简单且强大的静态网站托管服务。通过本教程，您应该能够成功部署您的单页面应用。如果遇到问题，可以查看 GitHub Pages 的官方文档或社区支持。