使用GitHub Action部署Expo应用至GitHub Pages遇问题求助

一、排查Action部署后网站未更新的核心原因 #

• 确认Workflow产物路径：检查Expo构建的静态文件目录（默认是web-build）是否完整生成并上传到部署分支。可以在Workflow中添加run: ls -la web-build步骤，查看是否包含index.html等关键文件。
• 验证Pages部署源设置：在仓库「Settings > Pages」中，确保「Source」选择「GitHub Actions」而非具体分支。保存设置后等待5分钟再刷新页面，避免系统缓存旧配置。
• 检查Workflow权限配置：必须在Workflow开头添加权限声明，保证有读写分支的权限：

  permissions:
    contents: write
    pages: write
    id-token: write
  

• 查看部署日志：在「Settings > Pages」底部的「Deployment history」中，点击最新部署记录，排查是否存在文件路径错误、权限不足等上传失败的报错。

二、解决切换回分支部署后网站崩溃的问题 #

• 清理旧分支缓存：Action与分支部署的产物混合会导致冲突，直接删除并重建gh-pages分支：

  git branch -D gh-pages
  git checkout --orphan gh-pages
  rm -rf .gitignore .github
  npx expo export:web
  mv web-build/* .
  rm -rf web-build
  git add .
  git commit -m "Re-deploy web build"
  git push origin gh-pages --force
  

• 确认分支部署根目录：在「Settings > Pages」选择分支部署时，指定根目录为/（因为已将web-build内容移到分支根目录），避免路径不匹配导致404或崩溃。
• 检查Expo baseUrl配置：如果GitHub Pages路径包含仓库名（如https://username.github.io/repo-name），需在app.json中添加配置："web": { "output": "static", "baseUrl": "/repo-name/" }，否则静态资源路径会出错。

三、长期稳定部署的建议 #

• 统一使用Action部署，避免切换模式引发的缓存冲突。完整Workflow示例：

  name: Deploy Expo Web to GitHub Pages
  on:
    push:
      branches: [main]
  jobs:
    deploy:
      runs-on: ubuntu-latest
      permissions:
        contents: write
        pages: write
        id-token: write
      environment:
        name: github-pages
        url: ${{ steps.deployment.outputs.page_url }}
      steps:
        - uses: actions/checkout@v4
        - uses: actions/setup-node@v4
          with:
            node-version: 20
            cache: 'npm'
        - run: npm install
        - run: rm -rf web-build && npx expo export:web
        - uses: actions/configure-pages@v4
        - uses: actions/upload-pages-artifact@v3
          with:
            path: './web-build'
        - uses: actions/deploy-pages@v4
          id: deployment
  

• 在Workflow中添加rm -rf web-build步骤，每次部署前清理旧产物，避免缓存干扰。

内容的提问来源于stack exchange，提问作者Lavínia Beghini