使用 GitHub Pages 部署单页面应用教程

简介

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

```

  1. 在 `package.json` 中添加 homepage 字段:

```json

{

"homepage": "https://username.github.io"

}

```

  1. 安装 gh-pages 包:

```bash

npm install --save-dev gh-pages

```

  1. 在 `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"

```

  1. 添加远程仓库:

```bash

git remote add origin https://github.com/username/username.github.io.git

```

  1. 推送代码:

```bash

git push -u origin main

```

前端框架项目:

  1. 构建项目:

```bash

npm run build

```

  1. 部署到 GitHub Pages:

```bash

npm run deploy

```

4. 访问网站

注意事项

  1. 确保仓库名称为 `username.github.io` 格式

  2. 确保仓库设置为 Public

  3. 如果使用自定义域名,需要在仓库设置中配置

  4. 部署后可能需要等待几分钟才能访问

常见问题解决

  1. 页面显示 404
  • 检查仓库名称是否正确

  • 确认文件是否在正确的分支

  • 检查 index.html 是否在根目录

  1. 样式或资源加载失败
  • 检查资源路径是否正确

  • 确保使用相对路径或完整的 GitHub Pages URL

  1. 部署后更新未生效
  • 清除浏览器缓存

  • 确认部署命令执行成功

  • 检查 GitHub Actions 状态(如果使用)

进阶配置

  1. 自定义域名
  • 在仓库设置中找到 "Pages" 选项

  • 在 "Custom domain" 中输入您的域名

  • 配置 DNS 记录

  1. 使用 GitHub Actions 自动部署
  • 创建 `.github/workflows` 目录

  • 添加部署配置文件

总结

GitHub Pages 是一个简单且强大的静态网站托管服务。通过本教程,您应该能够成功部署您的单页面应用。如果遇到问题,可以查看 GitHub Pages 的官方文档或社区支持。

相关推荐
钟爱蛋炒饭6 小时前
windows下使用github上传文件失败(编码问题)
github
molihuan11 小时前
开源 全平台 哔哩哔哩缓存视频合并 Github地址:https://github.com/molihuan/hlbmerge_flutter
android·flutter·缓存·ffmpeg·开源·github·音视频
CoderJia程序员甲13 小时前
GitHub 热榜项目 - 日榜(2025-10-03)
ai·开源·大模型·github·ai教程
绝无仅有16 小时前
面试复盘:哔哩哔哩、蔚来、字节跳动、小红书面试与总结
后端·面试·github
绝无仅有16 小时前
面试经历分享:从特斯拉到联影医疗的历程
后端·面试·github
CoderJia程序员甲1 天前
GitHub 热榜项目 - 日榜(2025-09-26)
ai·开源·github·ai编程·github热榜
CoderJia程序员甲1 天前
GitHub 热榜项目 - 日榜(2025-10-02)
ai·github·开源项目·github热榜
绝无仅有1 天前
资深面试题之MySQL问题及解答(二)
后端·面试·github
绝无仅有1 天前
某大厂库存秒杀的设计与实现总结
后端·面试·github
semantist@语校2 天前
语校网500所里程碑:日本语言学校数据库的标准化与可追溯机制
大数据·数据库·人工智能·百度·语言模型·oracle·github