GitHub Action部署静态Nuxt.js项目时GitHub Pages地址不符预期问题

1. 核心硬规则：仓库命名匹配用户级站点要求 #

GitHub 对无额外路径的用户级站点（即预期的 https://mortezasabihi.github.io 地址）有强制命名约束：

• 可生成根路径访问地址的用户级站点，仓库名必须严格为 mortezasabihi.github.io
• 如果你当前使用的是和账号完全同名的 mortezasabihi 仓库，默认生成的Pages访问地址必然是 https://mortezasabihi.github.io/mortezasabihi，和预期地址不匹配，这是最常见的问题根源

修复操作：进入仓库的「Settings -> General -> Repository name」页面，将现有仓库名修改为 mortezasabihi.github.io 并保存，GitHub会自动将其识别为用户级站点，对应访问域名自动切换为根路径地址。

2. 配置校验：Nuxt静态生成的路径匹配 #

静态站点部署到根路径时，路由基础路径配置错误会直接导致CSS、JS等静态资源全部404，页面空白：

• 打开项目根目录的 nuxt.config.js 文件，核对核心配置：

  export default {
    // 根路径部署时，必须将路由基础路径设为'/'
    router: {
      base: '/'
    },
    // 生成目录和工作流配置保持一致
    generate: {
      dir: 'dist'
    }
  }
  

• 如果之前曾配置过带旧仓库名的基础路径（比如 /mortezasabihi/），修改仓库名后必须同步调整为 /，否则部署后资源加载会全部失败。

3. 设置校验：GitHub Pages发布源配置 #

• 进入重命名后的仓库，打开「Settings -> Pages」页面：
  • 选择发布源为 Deploy from a branch
  • 分支选择 gh-pages，目录层级选择 / (root)
  • 不要将发布源设为「GitHub Actions」，当前使用 peaceiris/actions-gh-pages 是将构建产物推送到独立 gh-pages 分支的部署模式，和原生Actions部署源不兼容。

4. 优化：现有GitHub Action工作流的可调整点 #

你当前的工作流存在几处影响部署稳定性的冗余与过时配置：

• 触发规则冗余：pull_request 触发的部署没有实际生产价值，仅在主分支推送时执行部署即可
• 引用的Action版本过旧：Checkout和Setup Node动作都用了过时的主分支引用，Node14已停止长期维护
• 优化后的工作流参考配置：

  name: cd
  on:
    push:
      branches:
        - main # 替换为你实际使用的主分支名（如master）
  
  jobs:
    cd:
      runs-on: ubuntu-latest
      steps:
        - name: Checkout
          uses: actions/checkout@v3
  
        - name: Setup node env
          uses: actions/setup-node@v3
          with:
            node-version: 16
            cache: 'yarn'
  
        - name: Install dependencies
          run: yarn --frozen-lockfile
  
        - name: Generate static files
          run: yarn run generate
  
        - name: Deploy to gh-pages
          uses: peaceiris/actions-gh-pages@v3
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: ./dist
            force_orphan: true
  

修复后验证流程 #

1. 推送一次新的提交，等待工作流执行完成
2. 刷新Pages设置页面，等待状态从「准备中」切换为「已发布」
3. 清除本地浏览器缓存后访问 https://mortezasabihi.github.io，避免旧的路径重定向干扰验证结果。

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