GitHub Pages 免费静态网站部署教程

对于前端开发者、博主和开源爱好者而言，GitHub Pages 是一项极其好用的免费福利。它允许你直接从 GitHub 仓库托管静态网站（如 HTML、CSS、JS 文件），非常适合用于展示个人简历、技术博客或项目文档。本文将带你从零开始，掌握 GitHub Pages 的部署技巧。

一、 GitHub Pages 基础概念

GitHub Pages 支持两种类型的网站：

1. 用户/组织站点：仓库名必须为 username.github.io，部署后可以通过该域名直接访问。
2. 项目站点：依附于其他任意名称的仓库，部署后访问路径为 username.github.io/repository-name。

二、 极简部署：从分支直接发布

如果你的项目只有纯静态的 HTML/CSS/JS 文件（无需构建打包），部署极其简单。

1. 上传代码：将你的静态文件推送到 GitHub 仓库（通常推送到 main 分支）。确保仓库根目录下有一个 index.html 文件。
2. 开启 Pages 服务：
   • 进入仓库，点击顶部的 Settings 选项卡。
   • 在左侧边栏找到 Pages。
   • 在 Build and deployment 的 Source 下拉菜单中，选择 Deploy from a branch。
   • 在 Branch 设置中，选择包含代码的分支（如 main）和目录（通常是 / (root)）。
   • 点击 Save。
3. 等待发布：几分钟后，页面顶部会显示 "Your site is live at xxx"，点击链接即可访问。

---

三、 进阶部署：使用 GitHub Actions 构建前端项目

如果你使用的是 React, Vue, Hexo 或 Hugo 等需要编译的框架，可以通过 GitHub Actions 实现自动化构建与部署。

1. 配置 Actions

在 GitHub Pages 设置页面的 Source 中，选择 GitHub Actions。GitHub 会智能推荐适合你项目框架的 Workflow。

2. 编写 Workflow 文件

以 Node.js + Vue 项目为例，在 .github/workflows/deploy.yml 中配置如下逻辑：

• 检出代码 actions/checkout
• 设置 Node 环境 actions/setup-node
• 运行 npm install 与 npm run build
• 使用 actions/upload-pages-artifact 上传构建好的 dist 目录
• 使用 actions/deploy-pages 将产物发布到 Pages 环境

每次你向主分支推送代码，GitHub Actions 就会自动跑完这些步骤，免去了本地打包的烦恼。

---

四、 部署过程故障排查链路

在配置 GitHub Pages 的过程中，往往不会一帆风顺。遇到构建失败，请按以下逻辑排查：

1. 软件/配置问题

• 构建脚本错误：检查你的 package.json 中的 build 命令是否能在本地正常运行。
• Node 版本不匹配：如果本地构建成功但 Actions 报错，检查 Workflow 文件中指定的 Node.js 版本是否与本地一致。

2. 账号与权限问题

• Pages 权限未开启：有些组织的私有仓库可能限制了 Pages 的发布权限，需要组织管理员在组织设置中放开。

3. 网络问题（本地依赖拉取）

在使用 Hexo 等博客框架时，有时你在本地运行 npm install 会卡住，或者在配置主题时遇到网络超时，导致根本无法生成静态文件上传。

网络环境基础排查清单

• ✓ 确认已清除浏览器缓存和 Cookie
• ✓ 确认代理客户端（如 Clash/v2rayN）已正常启动并接管系统流量
• ✓ 确认当前节点并非处于故障或高延迟状态
• ✓ 尝试切换全局路由模式或更新本地分流规则
• ✓ 若为 PC 端，检查系统时间是否准确自动同步

完成上述基础排查后，再进行本教程针对性的深度检查。

本地构建依赖拉取失败，通常是因为无法连接至 npm registry 或 GitHub 源。此时检查你的本地网络代理是否正常。

4. 节点质量导致的本地调试困难

在本地预览和调试阶段，前端开发者需要频繁访问各类技术文档、拉取国外开源组件。如果你在网上随便找了个 VPN推荐，由于其 IP 在频繁更换且存在大量拥堵，会导致你本地 npm install 或者 git submodule update 极其缓慢甚至报错。

仍然存在网络连接问题？

如果账号、设备、浏览器、客户端和DNS均已排查，但仍出现连接超时、长连接中断、视频缓冲或出口IP频繁变化，可以继续查看对应场景的线路选择指南。

查看稳定线路指南

优化开发者体验： 建议开发者为自己配备一个 稳定机场，以保证在进行本地构建和依赖拉取时不会因为网络质量差而浪费时间。在寻找 机场推荐 时，重点关注那些专门针对开发者优化过路由、延迟低且不限制连接数的优质 翻墙机场。一个好用的网络环境，是保障本地开发、顺利推送至 GitHub Actions 完成部署的前提。

五、 总结

GitHub Pages 提供了强大而免费的托管服务。无论是简单的静态页面，还是基于现代前端框架的复杂应用，都可以通过页面配置或 GitHub Actions 轻松部署。排除了配置错误和本地网络依赖问题后，你就能将自己的作品向全世界展示。