配置相关脚本后仍无法通过GitHub Pages发布React网站

数据老陈

2026-8-10

React部署GitHub Pages失败排查方案

检查homepage字段格式：确保homepage严格匹配格式，仓库为用户主页仓库（即仓库名是<用户名>.github.io）时，写"homepage": "https://<用户名>.github.io"；普通仓库则写"homepage": "https://<用户名>.github.io/<仓库名>"，注意不要多写末尾斜杠，仓库名大小写要和GitHub上完全一致。
验证deploy脚本与依赖：确认package.json的scripts配置正确：
```
"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}
```
同时必须已安装gh-pages依赖，未安装则执行npm install gh-pages --save-dev。
核对GitHub Pages分支设置：进入仓库Settings -> Pages，确认Source选择的是gh-pages分支、根目录（/root），选错分支会直接导致部署失效，设置完成后等待5-10分钟让GitHub完成静态资源分发。

确认BrowserRouter的basename配置：index.js中的basename必须和仓库名完全一致，包括大小写，示例：

import { BrowserRouter } from 'react-router-dom';

ReactDOM.render(
  <BrowserRouter basename="/my-react-app">
    <App />
  </BrowserRouter>,
  document.getElementById('root')
);

注意basename开头的斜杠不能省略。

清除缓存重新部署：删除本地build文件夹（Mac/Linux执行rm -rf build，Windows执行rd /s /q build），再重新运行npm run deploy，避免旧缓存导致的资源不匹配问题。
检查仓库可见性：确认仓库是公开状态（Settings -> General -> Repository visibility），私有仓库需要GitHub Pro权限才能部署Pages，即使package.json中private设为false也无法绕过。
查看部署终端日志：执行npm run deploy时留意终端输出，若有gh-pages command not found、build失败等报错，根据提示修复对应问题，比如补全依赖、修正项目代码中的build错误。