使用 gh-pages 快速部署前端项目到 GitHub Pages

在前端开发中，把项目部署到线上环境是每个开发者都会遇到的环节。对于个人项目或静态网站，GitHub Pages 提供了免费的托管服务。而想要快速、自动化地将本地项目发布到 GitHub Pages，gh-pages 这个工具包是开发者的首选。

一、什么是 gh-pages

gh-pages 是一个 Node.js 工具包，用于将本地静态文件（HTML、CSS、JS 等）自动推送到 GitHub 仓库的一个分支上，从而通过 GitHub Pages 对外提供访问。

简而言之，它解决了两件事情：

1. 自动将本地构建好的静态文件上传到 GitHub。
2. 自动创建和维护用于 Pages 的分支（默认是 gh-pages）。

---

二、gh-pages 的工作原理

工作流程大致如下：

1. 本地构建项目
   将前端项目编译生成静态文件，例如 React 的 build 文件夹或 Vue 的 dist 文件夹。
2. 推送到指定分支
   gh-pages 会把这些文件推送到远程仓库的分支（默认 gh-pages）。
3. GitHub Pages 提供访问
   GitHub 会根据指定分支托管网站，用户即可通过 https://用户名.github.io/仓库名 访问。

可以理解为：gh-pages 就是一个“自动上传助手”，把本地文件打包并推送到 GitHub Pages 分支。

---

三、安装 gh-pages

在你的项目中安装即可：

npm install --save-dev gh-pages
# 或者使用 pnpm
pnpm add -D gh-pages

---

四、基本用法

假设你有一个 React 项目，构建目录是 build：

1. 构建项目

npm run build

2. 发布到 GitHub Pages

npx gh-pages -d build

参数说明：

• -d build → 指定要发布的本地目录
• 默认推送到 gh-pages 分支

执行完成后，GitHub Pages 会自动托管这些文件，你可以访问 https://用户名.github.io/仓库名。

---

五、在 package.json 中配置脚本

为了更方便，可以在 package.json 中配置：

{
  "scripts": {
    "predeploy": "npm run build",
    "deploy": "gh-pages -d build"
  }
}

执行：

npm run deploy

就会自动完成 构建 → 发布 的整个流程。

---

六、自定义分支和远程仓库

gh-pages 支持自定义分支和远程仓库：

npx gh-pages -d build -b custom-branch -r git@github.com:用户名/仓库名.git

参数说明：

• -b → 指定分支名（默认 gh-pages）
• -r → 指定远程仓库（可选）

这对于一些不想使用默认分支的项目非常有用。

---

七、使用注意事项

1. 只适合静态文件
   gh-pages 不能部署动态后端项目，它只处理 HTML、JS、CSS 等静态资源。
2. 分支会被覆盖
   每次部署都会覆盖目标分支内容，注意不要在该分支上手动添加其他文件。
3. 相对路径问题
   前端项目中 publicPath 或 homepage 配置要正确，否则资源可能 404。

---

八、小结

gh-pages 是前端开发者快速部署静态网站的利器：

• 自动创建分支并上传文件
• 支持自定义分支和远程仓库
• 可以和 predeploy 脚本结合，实现一键部署