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

相关推荐
掘金安东尼2 小时前
革新Web部署:Amazon Amplify Hosting!
后端·面试·github
掘金安东尼2 小时前
把复杂留给架构,把简单留给开发 —— Amazon Aurora DSQL 宣布:全面可用
面试·架构·github
掘金安东尼3 小时前
蔚来 600 亿研发成本,信还是不信。。
面试·程序员·github
喜欢吃豆4 小时前
深入企业内部的MCP知识(三):FastMCP工具转换(Tool Transformation)全解析:从适配到增强的工具进化指南
java·前端·人工智能·大模型·github·mcp
赋范大模型技术社区4 小时前
【LangChain 实战】多智能体协作实现浏览器自动化丨Agents 运行流程丨多工具串&并联调用
架构·github·代码规范
liangdabiao7 小时前
3分钟打造一个无敌的落地页Landing Page - 任何内容都完全自动化
程序员·github
海外空间恒创科技8 小时前
香港站群服务器与普通香港服务器对比
服务器·git·github
JinSo8 小时前
EasyEditor AI 聊天助手:让低代码开发更简单
前端·javascript·github
寻月隐君9 小时前
【Solana 开发实战】轻松搞定链上 IDL:从上传到获取全解析
后端·web3·github
ai小鬼头19 小时前
Ollama+OpenWeb最新版0.42+0.3.35一键安装教程,轻松搞定AI模型部署
后端·架构·github