Next.js应用本地运行正常，部署至GitHub Pages后显示默认页面求助

问题背景 #

• 本地运行localhost:3000完全正常，部署到GitHub Pages后仅显示Next.js默认欢迎页（"This is a Next.js project bootstrapped with create-next-app"）
• 使用GitHub Actions + gh-pages-deploy-action部署
• 仓库对应托管地址：mateuszkozlowski.github.io/krakow-airport/
• Next.js版本：15.0.4

已尝试操作：

• 配置next.config.js的basePath和assetPrefix
• 验证out文件夹包含导出的静态文件
• 确认GitHub Pages源设置为gh-pages分支

针对性解决方案 #

1. 确认静态导出配置与命令正确性

Next.js 13+（含15）的静态导出需明确配置，避免生成默认模板内容：

• 在next.config.js中启用静态导出并配置路径：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 必须配置，确保生成静态导出文件
  basePath: '/krakow-airport', // 匹配GitHub Pages的子路径
  assetPrefix: '/krakow-airport/',
}

module.exports = nextConfig

• 检查package.json的build命令，确保触发静态导出：

{
  "scripts": {
    "build": "next build && next export", // Pages Router需加next export；App Router仅需next build，但需确保output: 'export'配置
    "dev": "next dev"
  }
}

2. 修正GitHub Actions工作流配置

确保部署action正确指向out文件夹，避免上传错误内容：
推荐使用更稳定的peaceiris/actions-gh-pages替代原action，示例工作流（.github/workflows/deploy.yml）：

name: Deploy to GitHub Pages
on:
  push:
    branches: [main] # 替换为你的主分支名称
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20' # 匹配本地Node版本，避免依赖兼容性问题
      - name: Install dependencies
        run: npm install
      - name: Build static files
        run: npm run build
      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out # 确保指向正确的静态导出目录
          publish_branch: gh-pages

若坚持使用原gh-pages-deploy-action，需确认其build_dir参数设置为out。

3. 清理gh-pages分支残留内容

旧分支可能残留默认模板文件，导致新部署内容被覆盖：

• 本地切换到gh-pages分支：git checkout gh-pages
• 删除所有文件：rm -rf ./*
• 提交空分支：git add . && git commit -m "Clear outdated content" && git push origin gh-pages
• 切回主分支重新触发部署流程

4. 验证GitHub Pages部署状态

进入仓库Settings -> Pages，查看最近部署记录：

• 确认部署状态为成功
• 检查部署的文件列表，确保index.html是你的应用内容而非默认模板

5. 检查应用内资源与链接路径

确保应用内的资源引用、路由链接适配basePath：

• 使用next/link或useRouter时，无需手动添加basePath，Next.js会自动处理
• 手动编写的静态资源路径（如img、script）需通过环境变量引入basePath：

<img src={`${process.env.NEXT_PUBLIC_BASE_PATH}/assets/logo.png`} alt="Logo" />

（需在.env中配置NEXT_PUBLIC_BASE_PATH=/krakow-airport）

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