Github Pages预览dist目录index.html而非README的问题求助

问题根源 #

Github Pages默认优先读取仓库根目录的index.html，而你的webpack打包产物全部存放在/dist目录下，若未正确配置Github Pages的发布路径，就只会展示根目录的README文件。之前添加的permalink是Jekyll专属配置，会干扰路径解析导致404。

修复步骤 #

1. 配置Github Pages发布目录 #

• 进入仓库的「Settings」页面，找到「Pages」选项卡
• 在「Source」区域，选择main分支，然后从下拉菜单中选中/dist作为发布目录（如果看不到该选项，先确认本地打包后的dist文件夹已推送到远程仓库）
• 保存设置后等待数分钟，Github Pages会重新部署

2. 确保dist文件夹已提交到仓库 #

• 检查.gitignore文件，若存在dist/条目，删除或注释掉该行
• 执行以下命令提交dist文件夹：

  git add dist/
  git commit -m "提交打包产物dist"
  git push origin main
  

3. 移除错误的permalink配置 #

• 删除README文件中添加的permalink: ./dist/index.html，该配置属于Jekyll静态站点工具，会破坏Github Pages的默认路径规则，引发404错误

可选：用Github Actions自动构建部署 #

如果不想手动提交dist文件夹，可以配置Github Actions实现代码推送后自动打包部署：

• 在仓库根目录创建.github/workflows/deploy.yml文件，写入以下内容：

  name: 部署到Github Pages
  on:
    push:
      branches: [main]
  jobs:
    build-and-deploy:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - name: 配置Node.js环境
          uses: actions/setup-node@v4
          with:
            node-version: '20'
        - name: 安装依赖
          run: npm install
        - name: 打包项目
          run: npm run build
        - name: 部署到Pages
          uses: peaceiris/actions-gh-pages@v4
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./dist
  

• 配置完成后，每次推送到main分支，Github Actions会自动完成依赖安装、打包和部署流程

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