GitHub Actions部署GitHub Pages遇404错误（缺失index.html）求助

核心排查点 #

你推测的没错，404错误大概率是因为GitHub Pages找不到首页文件。先确认两个关键点：

• 本地运行或构建项目后，是否存在index.html文件？
• 这个文件是否在构建输出目录的根路径下？

GitHub Actions部署实操步骤 #

1. 配置GitHub Pages源
   进入仓库的Settings -> Pages，在Build and deployment区域，将Source切换为GitHub Actions，保存设置。

2. 创建部署工作流文件
   在项目根目录新建.github/workflows/deploy.yml，根据项目类型填入对应内容：

   name: Deploy to GitHub Pages
   
   on:
     push:
       branches: [ main ] # 替换成你的主分支名，比如master
     workflow_dispatch:
   
   jobs:
     deploy:
       runs-on: ubuntu-latest
       steps:
         - name: 拉取代码
           uses: actions/checkout@v4
   
         # 以下两步针对需要构建的项目（如npm管理的项目），纯静态项目可直接删除
         - name: 安装依赖
           run: npm install
   
         - name: 构建项目
           run: npm run build # 替换成你的实际构建命令，比如npm run dev:build
   
         - name: 部署到GitHub Pages
           uses: peaceiris/actions-gh-pages@v4
           with:
             github_token: ${{ secrets.GITHUB_TOKEN }}
             publish_dir: ./dist # 替换成构建输出目录，比如./build或根目录./
   

3. 适配项目的配置调整

   • 纯静态项目（无需构建）：删除安装依赖和构建项目步骤，将publish_dir设为./，同时确保根目录下存在index.html。
   • 构建输出目录非dist：把publish_dir改成实际的输出路径，比如./build。

验证与调试 #

• 推送代码后，进入仓库的Actions标签，查看工作流是否执行成功。如果有报错，优先修复构建或依赖问题。
• 工作流成功后，等待1-2分钟，访问GitHub Pages提供的域名，确认页面正常加载。

分支部署失败的补充说明 #

如果尝试分支部署（如gh-pages分支），需要：

• 确保静态文件（或构建后的文件）被推送到gh-pages分支的根目录。
• 在Settings -> Pages里选择gh-pages分支及对应目录（如/root）。

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