React项目GitHubPages部署教程

在前端开发内容学习中，React项目GitHub Pages部署教程：配置gh-pages并完成页面访问验证是常见主题。很多人在阅读时会遇到概念分散、步骤不清和注意点难以归纳的问题。本文按照基础概念、操作流程和关键细节，对相关内容进行整理。

部署完成后应该看到 GitHub Pages 发布地址

React 项目部署成功后，GitHub Pages 设置页会显示已发布的站点地址，并且页面来源通常指向 gh-pages 分支。这个结果比单纯看到命令行“成功”更可靠，因为它说明 GitHub 已经接收到构建产物并开始对外提供静态页面。

图1：GitHub Pages 已显示发布地址和 gh-pages branch，这是部署完成后最重要的核对位置。

部署前先确认 React 项目和 GitHub 仓库条件

开始前需要有一个可以正常运行的 React 项目，并且项目已经提交到 GitHub 仓库。建议先在本地执行 npm start 或 yarn start 确认开发环境可用，再执行 git status 确认当前改动是否已提交；如果还有未保存的业务代码，不要急着部署，先提交或备份。

GitHub Pages 适合发布纯前端静态页面。React Router 如果使用浏览器历史模式，刷新子路径可能出现 404，需要额外配置重定向；新手第一次部署建议先用根路径或 Hash 路由验证流程，等发布链路跑通后再处理路由细节。

配置 React 项目的 homepage 和部署脚本

第1步：安装 gh-pages 依赖

在项目根目录打开终端，执行 npm install gh-pages --save-dev，如果项目使用 Yarn，也可以执行 yarn add gh-pages --dev。这个依赖的作用是把 build 目录里的静态文件推送到 GitHub 仓库的 gh-pages 分支。

安装完成后，package.json 的开发依赖中应出现 gh-pages。如果安装过程提示权限或网络问题，先换用稳定网络或检查 npm registry，不要直接跳到部署命令。

第2步：填写 homepage 地址

第3步：添加 predeploy 和 deploy 脚本

继续在 package.json 的 scripts 中加入两个脚本：predeploy 用来自动执行构建，deploy 用来发布 build 目录。常见写法是 "predeploy":"npm run build" 和 "deploy":"gh-pages -d build"。

如果你使用 Yarn，脚本仍然可以保留同样的命令；真正执行时用 yarn deploy 即可。修改后保存文件，并确认 JSON 逗号没有多写或漏写，否则后面运行命令会直接报解析错误。

运行部署命令并检查构建输出

第4步：执行 npm run deploy 或 yarn deploy

回到项目根目录执行 npm run deploy，使用 Yarn 的项目执行 yarn deploy。命令会先生成优化后的生产构建，再把构建产物推送到远程 gh-pages 分支。第一次执行时可能要求 GitHub 登录或令牌授权，需要按终端提示完成认证。

图2：终端出现 Compiled successfully 和 build folder is ready，说明 React 生产包已经生成，可以进入发布分支检查。

如果终端停在权限错误，先确认当前 Git 远程地址是否有写入权限；如果提示找不到 gh-pages 命令，说明依赖没有安装成功，需要重新安装后再执行部署。

在 GitHub Pages 中选择发布来源

第5步：进入仓库 Pages 设置

打开 GitHub 仓库，进入 Settings → Pages。在 Source 区域选择发布方式。使用 gh-pages 工具部署时，通常选择 Deploy from a branch，再把分支设为 gh-pages，目录选择 /root 或页面提示的默认目录。

图3：在 Pages 的 Source 区域选择 Deploy from a branch，用于确认仓库从分支发布静态页面。

保存后 GitHub 可能需要等待一小段时间才生成访问地址。页面显示绿色提示或出现站点 URL 后，再点击访问；如果刚保存就打开，看到 404 并不一定代表失败，可以等待构建状态更新后重试。

访问页面并排查空白页或 404

第6步：用发布地址做最终验证

点击 GitHub Pages 给出的站点地址，确认首页能正常打开，并检查浏览器地址是否与 homepage 设置一致。再打开开发者工具的 Network 面板，如果 JS 或 CSS 返回 404，通常是 homepage 路径写错；如果首页可打开但刷新二级页面 404，多半是路由模式需要调整。

• 页面空白：优先检查 homepage 是否漏了仓库名，重新执行 npm run deploy 后再刷新。

• 仓库没有 gh-pages 分支：说明部署命令没有成功推送，检查 GitHub 权限、远程地址和终端报错。

• Pages 设置里没有新分支：等待片刻刷新仓库页面，或确认部署命令是不是推送到了另一个远程仓库。

总结

React 项目部署到 GitHub Pages 的关键不是只运行一个命令，而是让 homepage、gh-pages 分支、Pages 发布来源和最终访问地址保持一致。新手按“本地可运行—配置路径—执行部署—Pages 设置—访问验证”的顺序排查，基本能定位大多数部署失败问题。