使用 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 小时前
腾讯面试文章解析:MySQL慢查询,存储引擎,事务,结构算法等总结与实战
后端·面试·github
逛逛GitHub7 小时前
这个 OCR 开源项目天花板,杀疯了。
github
徐sir(徐慧阳)8 小时前
搭建属于自己的网站HEXO静态页(二)发布网站到gihub
服务器·node.js·github·hexo
哈喽哈喽哈喽~8 小时前
推送文件到github ---服务器关键配置内容
运维·服务器·经验分享·github
技术爬爬虾10 小时前
AI编程新王Codex详细攻略,一期视频精通,附免费使用方法
程序员·github
散峰而望11 小时前
基本魔法语言分支和循环 (二) (C语言)
c语言·开发语言·github·visual studio
期待のcode11 小时前
gitee与github远程仓库
gitee·github
半桔14 小时前
【IO多路转接】IO 多路复用之 select:从接口解析到服务器实战
linux·服务器·c++·github·php
Moment15 小时前
为什么 Electron 项目推荐使用 Monorepo 架构 🚀🚀🚀
前端·javascript·github
掘金安东尼15 小时前
🧭前端周刊第437期(2025年10月20日–10月26日)
前端·javascript·github