使用 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 的官方文档或社区支持。

相关推荐
qianmoQ19 分钟前
GitHub 趋势日报 (2025年07月27日)
github
SpiderPex5 小时前
GitHub下载项目完整配置SSH步骤详解
运维·ssh·github
codervibe9 小时前
从毕业设计到企业级模板:一次 Spring Boot 后端项目目录结构重构实录
后端·github
Github项目推荐10 小时前
Rust生态系统在Web开发中的优势(9754)
面试·github
一念&11 小时前
Git 与 GitHub 的对比与使用指南
git·github
OpenTiny社区13 小时前
面试官:讲讲 Vue Vapor 事件机制?我甩出了这份实测报告!
前端·vue.js·github
mortimer14 小时前
PyInstaller打包踩坑记:从静默崩溃到柳暗花明
人工智能·python·github
天天码行空17 小时前
Radash: 新一代前端工具库平替Lodash库
前端·javascript·github
GoGeekBaird17 小时前
大模型应用的五大拦路虎:一位从业者的深度反思与破局指南
后端·github
MarkGosling18 小时前
【开源项目】轻量加速利器 HubProxy自建 Docker、GitHub 下载加速服务
docker·容器·github