部署Next.js 14电商应用至Github Pages仅显示README求助

核心排查与修复步骤 #

1. 修正 Next.js 静态导出配置 #

Next.js 14 部署到 Github Pages 必须开启静态导出模式，否则无法生成兼容的静态资源：

• 在项目根目录的 next.config.js 中添加以下配置：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  basePath: '/strength-palace', // 必须和你的仓库名称完全一致
  images: {
    unoptimized: true, // 静态导出时禁用图片优化功能
  },
}

module.exports = nextConfig

2. 检查部署产物与分支内容 #

• 执行 npm run build 后，根目录会生成 out 文件夹，里面是完整的静态部署资源。
• 若使用 gh-pages 包部署，确保 package.json 中的脚本正确：

"scripts": {
  "build": "next build",
  "deploy": "gh-pages -d out"
}

• 查看 gh-pages 分支内容：分支根目录必须是 out 文件夹里的所有文件（如 index.html、_next 文件夹等），不能包含仓库根目录的 README 文件，否则 Github Pages 会优先显示 README。

3. 确认 Github Pages 源设置 #

进入仓库的「Settings → Pages → Build and deployment」：

• 选择「Deploy from a branch」
• 分支选择 gh-pages，文件夹选择 /root
• 保存后等待 Github 完成重新部署

4. 清理缓存并重新部署 #

• 删除本地旧的 gh-pages 分支，重新执行部署：

git branch -D gh-pages
npm run deploy

• 访问页面时按 Ctrl+F5 强制刷新浏览器，清除本地缓存

5. 校验 Github Actions 配置（若使用 Actions 部署） #

确保工作流文件（如 .github/workflows/deploy.yml）正确将 out 文件夹内容部署到 gh-pages 分支，示例配置：

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./out

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