首次部署Webpack5项目至Github Pages，图片/Sass资源无法加载求助

核心问题总结 #

• 资源根路径不匹配：Github Pages部署后你的项目处于子路径/Travlog/下，但Webpack默认将资源路径解析为根目录/开头，导致浏览器去https://shopeyin.github.io/xxx找资源，而实际资源在https://shopeyin.github.io/Travlog/xxx路径下。
• 开发模式构建不适合部署：你用mode: 'development'构建，且用style-loader把CSS注入JS，这种方式在部署环境下易出现路径解析问题；直接访问源码目录的template.html毫无意义——Sass未编译、资源路径未被Webpack处理，必然加载失败。
• 部署对象错误：不应把整个项目（包括src）部署到Github Pages，正确做法是只部署Webpack构建后的dist目录内容。

具体解决步骤 #

1. 配置Webpack的publicPath #

在output配置中添加publicPath，匹配Github Pages的子路径：

output: {
  path: path.resolve(__dirname, 'dist'),
  filename: '[name][contenthash].js',
  clean: true,
  assetModuleFilename: '[name][ext]',
  publicPath: '/Travlog/' // 对应项目在Github Pages的子路径
}

如果要兼容本地开发和部署，也可以用相对路径：

publicPath: './'

2. 切换生产模式并提取独立CSS文件 #

开发模式的构建产物不适合部署，改成生产模式，并使用MiniCssExtractPlugin替代style-loader生成独立CSS文件：

• 先安装插件：

npm install mini-css-extract-plugin --save-dev

• 修改Webpack配置：

const MiniCssExtractPlugin = require('mini-css-extract-plugin');

module.exports = {
  mode: 'production', // 切换为生产模式
  // ...其他原有配置
  module: {
    rules: [
      {
        test: /\.scss$/,
        use: [MiniCssExtractPlugin.loader, 'css-loader', 'sass-loader'], // 替换style-loader
      },
      // ...其他规则
    ],
  },
  plugins: [
    new MiniCssExtractPlugin({
      filename: '[name][contenthash].css' // 生成带哈希的CSS文件
    }),
    // ...其他原有插件
  ],
}

3. 正确部署dist目录到Github Pages #

推荐用gh-pages工具自动部署，步骤如下：

• 安装工具：

npm install gh-pages --save-dev

• 在package.json中添加部署脚本：

"scripts": {
  "build": "webpack",
  "deploy": "gh-pages -d dist"
}

• 执行部署：

npm run build
npm run deploy

部署完成后，直接访问https://shopeyin.github.io/Travlog/即可（无需加dist路径）。

4. 禁止直接访问src目录文件 #

源码目录的template.html未经过Webpack处理，不存在可正常加载的资源，只需关注部署后的dist目录内容即可。

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