解决GitHub Pages无法加载Webpack构建React项目图片及部署问题

我手动搭建了一个React项目（未使用Create React App），通过将项目打包至build文件夹并使用gh-pages模块，成功部署到了GitHub Pages。但部署后图片无法显示，虽然看起来图片文件已存在；本地运行npm start时图片可正常加载。

仓库地址：harry-z-huang/restaurant-v2

此外，我希望获取Webpack项目正确部署的建议，我怀疑当前打包至build文件夹的方式有误，但按部分方案建议打包至根目录也无法生效。

package.json配置 #

{
  "name": "reactappscratch",
  "version": "1.0.0",
  "homepage": "https://harry-z-huang.github.io/restaurant-v2/",
  "repository": {
    "url": "git+https://harry-z-huang.github.io/restaurant-v2/"
  },
  "description": "",
  "main": "index.js",
  "scripts": {
    "start": "nodemon --watch src --exec 'webpack-dev-server --mode development --hot --open'",
    "build": "webpack --mode production",
    "deploy": "npm run build && gh-pages -d build"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@emotion/react": "^11.10.5",
    "@emotion/styled": "^11.10.5",
    "@mui/material": "^5.11.7",
    "@reduxjs/toolkit": "^1.9.2",
    "css-loader": "^6.7.3",
    "jquery": "^3.6.3",
    "morgan": "^1.10.0",
    "pg": "^8.9.0",
    "react-redux": "^8.0.5",
    "style-loader": "^3.3.1"
  },
  "devDependencies": {
    "@babel/core": "^7.20.12",
    "@babel/preset-env": "^7.20.2",
    "@babel/preset-react": "^7.18.6",
    "@pmmmwh/react-refresh-webpack-plugin": "^0.5.10",
    "babel-loader": "^9.1.2",
    "express": "^4.18.2",
    "gh-pages": "^5.0.0",
    "nodemon": "^2.0.20",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-refresh": "^0.14.0",
    "webpack": "^5.75.0",
    "webpack-cli": "^5.0.1",
    "webpack-dev-server": "^4.11.1"
  }
}

webpack配置 #

const path = require('path');

module.exports = {
  entry: './src/index.js',
  output: {
    path: __dirname + '/build',
    filename: 'bundle.js'
  },
  module: {
    rules: [
      {
        test: /\.jsx?$/,
        exclude: /node_modules/,
        loader: 'babel-loader',
        options: {
          presets: ['@babel/preset-env', '@babel/preset-react'],
        },
      },
      {
        test: /\.css$/i,
        use: ["style-loader", "css-loader"],
      },
    ],
  },
};

图片不显示的核心原因 #

1. Webpack未配置图片资源的处理规则，导致打包时图片未被正确输出到build目录或路径引用错误
2. 部署到GitHub Pages子路径（/restaurant-v2/）时，未设置Webpack的publicPath，导致资源引用路径以根目录开头，无法匹配子路径下的资源

具体修复步骤 #

1. 配置Webpack处理图片资源 #

Webpack 5推荐使用Asset Modules替代传统的file-loader，在webpack.config.js的module.rules中添加图片处理规则：

module: {
  rules: [
    // ... 已有的jsx、css规则
    {
      test: /\.(png|svg|jpg|jpeg|gif)$/i,
      type: 'asset/resource',
    },
  ],
}

该规则会自动将图片文件输出到build目录，并在代码中替换为正确的引用路径。

2. 设置publicPath适配GitHub Pages子路径 #

在webpack.config.js的output中添加publicPath，值为你的GitHub Pages子路径（即仓库名）：

output: {
  path: path.resolve(__dirname, 'build'), // 改用path.resolve避免路径拼接问题
  filename: 'bundle.js',
  publicPath: '/restaurant-v2/'
}

3. 修正package.json中的repository字段 #

当前repository的url指向了Pages地址，应改为仓库的Git地址：

"repository": {
  "url": "git+https://github.com/harry-z-huang/restaurant-v2.git"
}

4. 验证图片引用路径 #

确保代码中图片的引用是相对路径（如./images/logo.png），而非绝对路径（如/images/logo.png），Webpack会自动结合publicPath转换为正确的部署路径。

通用Webpack项目部署GitHub Pages建议 #

• 静态资源处理：始终为图片、字体等静态资源配置Webpack处理规则，避免资源丢失或路径错误
• publicPath设置：部署到子路径时必须设置publicPath为仓库名，确保资源引用正确
• 本地预验证：打包完成后，使用npx serve build命令本地预览build文件夹，确认所有资源加载正常后再部署
• gh-pages部署：确保deploy脚本中gh-pages -d build指向正确的打包目录，无需将打包文件放到根目录
• GitHub Pages配置：在仓库设置中确认部署来源为gh-pages分支的/root路径

内容的提问来源于stack exchange，提问作者Harry Z. Huang