如何在Github Pages部署主分支子目录中的React项目

我有一个名为my-projects的GitHub仓库，里面包含多个文件夹，每个文件夹对应一个独立的Web项目。这个仓库的GitHub Pages站点当前基于main分支（而非gh-pages分支）构建，使用GitHub Jekyll主题。

仓库简化后的文件结构如下：

my-projects/
├─ project1/
│  ├─ index.html
│  ├─ README.md
├─ project2/
│  ├─ index.html
│  ├─ README.md
├─ project3/
│  ├─ README.md
│  ├─ dist/
│  │  ├─ index.html
├─ project4/
│  ├─ README.md
│  ├─ node_modules/
│  ├─ public/
│  ├─ build/
│  ├─ package.json
│  ├─ package-lock.json
│  ├─ src/
├─ config.yml
├─ README.md

部分项目的生产构建文件存在dist文件夹中，以下链接均为已成功部署的GitHub Pages站点：

• http://username.github.io/my-projects/
• http://username.github.io/my-projects/project1
• http://username.github.io/my-projects/project2
• http://username.github.io/my-projects/project3/dist

project4是用create-react-app生成的React应用，其package.json内容如下：

{  
  "name": "my-projects",  
  "version": "0.1.0",  
  "private": true,  
  "homepage": "http://username.github.io/my-projects/project4",  
  "dependencies": {    
    "@testing-library/jest-dom": "^5.16.5",    
    "@testing-library/react": "^13.4.0",    
    "@testing-library/user-event": "^13.5.0",    
    "bootstrap": "^5.2.3",    
    "date-fns": "^2.29.3",    
    "react": "^18.2.0",    
    "react-bootstrap": "^2.7.0",    
    "react-dom": "^18.2.0",    
    "react-icons": "^4.7.1",    
    "react-scripts": "5.0.1",    
    "react-to-print": "^2.14.12",    
    "uniqid": "^5.4.0",    
    "web-vitals": "^2.1.4"  
  },  
  "scripts": {    
    "start": "react-scripts start",    
    "build": "react-scripts build",    
    "test": "react-scripts test",    
    "eject": "react-scripts eject"  
  },  
  "eslintConfig": {    
    "extends": [      
      "react-app",      
      "react-app/jest"    
    ]  
  },  
  "browserslist": {    
    "production": [      
      ">0.2%",      
      "not dead",      
      "not op_mini all"    
    ],    
    "development": [      
      "last 1 chrome version",      
      "last 1 firefox version",      
      "last 1 safari version"    
    ]  
  }
}

我通过npm run build生成生产构建文件并推送到GitHub后，无法正常访问站点：

• http://username.github.io/my-projects/project4显示的是project4的README文件，而非项目本身；
• http://username.github.io/my-projects/project4/build显示空白页面，控制台报资源404错误：

main.80069716.js:1          Failed to load resource: the server responded with a status of 404 ()
main.0634878b.css:1          Failed to load resource: the server responded with a status of 404 ()
manifest.json:1          Failed to load resource: the server responded with a status of 404 ()
manifest.json:1 Manifest: Line: 1, column: 1, Syntax error.
main.0634878b.css:1          Failed to load resource: the server responded with a status of 404 ()
manifest.json:1          Failed to load resource: the server responded with a status of 404 ()
DevTools failed to load source map: Could not load content for chrome-extension://gighmmpiobklfepjocnamgkkbiglidom/browser-polyfill.js.map: System error: net::ERR_FILE_NOT_FOUND
DevTools failed to load source map: Could not load content for chrome-extension://clldacgmdnnanihiibdgemajcfkmfhia/contentScript.js.map: System error: net::ERR_BLOCKED_BY_CLIENT

• 试过用gh-pages分支的部署教程，但切换分支后其他项目无法访问，只能改回main分支；
• 将package.json的homepage设为.，还是出现空白页和相同报错；
• 将homepage设为http://username.github.io/my-projects/project4/build/，问题依旧。

• http://username.github.io/my-projects/project4仍显示project4的README；
• http://username.github.io/my-projects/project4/build正常显示生产构建页面；
• 其他站点如http://username.github.io/my-projects/project2仍可正常访问。

1. 修正React应用的homepage配置 #

将package.json中的homepage改为：

"homepage": "/my-projects/project4/build/"

该配置会告诉React构建时，所有静态资源的路径基于仓库根目录下的project4/build文件夹，确保资源能被正确加载。

2. 禁用Jekyll对build文件夹的处理 #

由于你的GitHub Pages使用Jekyll主题，Jekyll默认会解析仓库内的文件，但build文件夹里的静态资源不需要Jekyll处理。在仓库根目录创建一个空的.nojekyll文件，GitHub Pages会跳过Jekyll对这类静态文件夹的解析，直接托管文件。

同时，可在根目录的_config.yml中添加排除规则，避免Jekyll处理不必要的文件：

exclude:
  - project4/node_modules/
  - project4/src/
  - project4/public/

3. 重新构建并推送 #

在project4目录下重新执行构建命令：

npm run build

将更新后的build文件夹内容推送到GitHub的main分支即可。

验证 #

完成上述步骤后，http://username.github.io/my-projects/project4/build应能正常加载React应用，http://username.github.io/my-projects/project4仍会显示README文件，其他项目的访问不受影响。

内容的提问来源于stack exchange，提问作者kelvin