Next.js部署GitHub Pages时图片与图标加载失败求助

1. 配置next.config.js关键参数 #

GitHub Pages部署Next.js必须适配静态导出规则，同时根据站点类型配置路径前缀：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export', // 启用静态导出模式，适配GitHub Pages环境
  // 若为项目站点（如username.github.io/my-next-app），需设置以下两项
  basePath: '/my-next-app', // 替换为你的仓库名称
  assetPrefix: '/my-next-app/', // 注意末尾斜杠，与basePath保持一致
  // 若为个人/组织主页（username.github.io），删除basePath和assetPrefix即可
}

module.exports = nextConfig

2. 规范public资源引用方式 #

代码中引用public内的资源时，使用根路径起始的绝对路径，无需手动拼接basePath（Next.js会自动处理）：

• 图片示例：<img src="/logo.png" alt="站点Logo" />
• Favicon示例（在app/layout.js或pages/_document.js中）：<link rel="icon" href="/favicon.ico" />

3. 确认构建与部署脚本 #

在package.json中配置正确的命令，并安装部署依赖：

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

执行命令安装依赖：npm install gh-pages --save-dev

4. 检查GitHub Pages部署源 #

进入仓库Settings → Pages页面，确认部署源为gh-pages分支的/root目录，避免选择错误分支或子路径。

5. 清除缓存并重新部署 #

• 删除本地.next和out文件夹，重新执行npm run build && npm run deploy
• 若页面仍有缓存，可在GitHub Pages页面等待5-10分钟，或手动触发重新部署

6. 验证静态文件结构 #

构建完成后查看out文件夹，确认图片、favicon等资源已正确生成，且HTML文件中资源路径已自动拼接basePath（如/my-next-app/logo.png）。

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