部署Next.js至GitHub Pages时部分图片无法加载求助

• 配置基础路径（必做）
  GitHub Pages部署在子路径/bahana，Next.js默认会以根路径加载资源，导致路径错误。在next.config.js中添加以下配置：

  /** @type {import('next').NextConfig} */
  const nextConfig = {
    basePath: '/bahana',
    assetPrefix: '/bahana/',
    output: 'export', // 启用静态导出适配GitHub Pages
  }
  
  module.exports = nextConfig;
  

  配置后，所有静态资源的路径会自动加上/bahana前缀，匹配GitHub Pages的部署路径。

• 统一图片引用方式

  • 优先使用Next.js的Image组件，配合public文件夹路径：比如src="/images/your-image.png"，basePath会自动处理前缀。
  • 静态导入图片：通过import img from '../public/images/your-image.png'导入，然后在组件中使用src={img.src}，这种方式Next.js会自动处理构建后的路径，避免手动写错。
  • 避免使用相对路径（如./images/xxx.png），尤其是在嵌套组件或页面中，部署后相对路径会失效。

• 检查文件名大小写
  GitHub Pages的文件系统区分大小写，而本地Windows/macOS默认不区分。比如本地命名MyImage.png，但仓库里是myimage.png，部署后就会找不到图片。确保本地文件名和GitHub仓库中的完全一致，统一大小写格式。

• 验证静态导出文件
  执行next build后，检查生成的out文件夹，确认所有不显示的图片都存在于对应路径下。如果缺失，检查图片是否放在public文件夹中（Next.js只会打包public下的静态资源），或者是否在next.config.js中配置了额外的资源目录。

• 检查部署分支文件结构
  查看仓库的gh-pages分支，确认图片是否上传到了bahana/images（或对应路径）下。如果图片缺失，重新执行部署命令，确保构建产物完整上传。

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