Next.js部署GitHub Pages仅显示README、加载慢问题咨询

两个问题均为配置错误导致，按以下步骤修正即可：

核心错误点 #

• 站点显示README的直接原因：gh-pages 部署分支根目录缺失有效index.html入口，GitHub Pages找不到首页文件就会默认渲染根目录的README.md。你手动单独推送_next文件夹的操作会覆盖分支原有文件结构，冲掉自动生成的入口文件；同时路径配置错误导致静态资源无法正确映射。
• 访问速度慢的直接原因：配置字段写法、位置错误导致assetPrefix完全不生效，大量静态资源请求404后重试拖慢加载；.nojekyll放置位置错误（放在_next文件夹内而非部署根目录），GitHub Pages默认拦截下划线开头的_next静态资源目录，资源加载被拦截。

逐点修复步骤 #

1. 修正next.config.js配置，删除原有错误配置，替换为以下内容：

const isProd = process.env.NODE_ENV === 'production';
const repoPath = '/amazon-clone';

module.exports = {
  // 生产环境自动匹配仓库子路径，开发环境不配置避免影响本地调试
  assetPrefix: isProd ? repoPath : '',
  basePath: isProd ? repoPath : '',
  trailingSlash: true, // 适配GitHub Pages静态路由匹配规则
  images: {
    unoptimized: true, // GitHub Pages不支持Next.js默认图片优化服务，必须关闭
    domains: ["fakestoreapi.com"],
  },
  env: {
    PUBLIC_URL: isProd ? "https://imangi.github.io/amazon-clone" : "http://localhost:3000",
  },
};

注意：原配置里Images字段大写、assetPrefix写在env块内都是错误写法，Next.js无法识别这些配置。
2. 删除你创建的replacer.js文件，不需要手动替换路径：Next.js原生的basePath和assetPrefix会自动处理所有页面、静态资源的路径前缀，手动替换不仅冗余，还容易出现路径匹配遗漏。同时你本地并未安装replace-in-file依赖，原有替换脚本执行时本身就会报错。
3. 修正package.json内的脚本配置，删除冗余的replaceFilePaths、export脚本，替换为以下内容：

{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "next",
    "build": "next build && next export -o build",
    "postbuild": "touch build/.nojekyll", // 构建后自动在输出根目录生成.nojekyll，避免_next文件夹被拦截
    "deploy": "gh-pages -d build -t", // -t参数强制推送包含.nojekyll在内的所有隐藏文件
    "predeploy": "npm run build",
    "start": "next start"
  }
}

4. 清理旧部署缓存与错误分支内容：

• 本地执行npx gh-pages-clean清除gh-pages本地缓存，避免旧错误文件被重复推送。
• 进入GitHub仓库的Pages设置页，确认部署源选择gh-pages分支的根目录，不要指定其他子文件夹。

5. 重新执行部署命令npm run deploy即可，不需要手动向gh-pages分支推送任何文件，部署脚本会自动将构建产物全量同步到分支。

验证注意事项 #

• 部署完成后用Ctrl+F5强制刷新浏览器清缓存，避免本地旧缓存导致页面显示异常。
• 后续不要手动修改gh-pages分支的任何内容，所有部署文件都通过构建脚本自动生成推送，手动上传很容易破坏目录结构导致入口失效。

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