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