配置basePath与assetPrefix后，NextJS部署至GitHub Pages仍失败

核心配置修正 #

• 确保next.config.js的配置完整，尤其是尾部斜杠和输出类型：

  module.exports = {
    basePath: '/website',
    assetPrefix: '/website/',
    trailingSlash: true, // GitHub Pages要求静态文件路径带尾部斜杠，否则触发404
    output: 'export', // Next.js 13+ 必须声明该字段才能生成纯静态文件
  }
  

• 检查package.json中的部署命令，确保推送out目录到gh-pages分支时允许隐藏文件：

  "scripts": {
    "deploy-gh": "gh-pages -d out -t true"
  }
  

  -t true参数用于推送.nojekyll这类隐藏文件，避免GitHub Pages忽略静态资源。

资源引用规范 #

• 所有静态资源（图片、字体等）不要用硬编码的绝对路径，优先使用Next.js的Image组件或public目录的相对路径，basePath会自动补全前缀：
  错误写法：/images/logo.png
  正确写法：使用Image组件时直接写src="/images/logo.png"，Next.js会自动拼接/website前缀
• 页面路由跳转必须使用Next.js的Link组件，不要用原生<a>标签，确保路由自动适配basePath。

部署流程验证 #

1. 执行yarn build后，检查out目录结构，确认所有静态文件都包含在out/website子目录下
2. 用npx serve out本地预览，访问http://localhost:3000/website，验证页面和资源加载是否正常，提前排查问题
3. 推送gh-pages分支后，在GitHub仓库的「Settings -> Pages」中确认部署分支为gh-pages，部署目录选择/root

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