部署在GitHub Pages的Next.js应用图片无法加载问题

问题概述 #

使用Next.js开发的应用部署到GitHub Pages后图片无法加载，仓库名为ecommerce-product-page。排查发现图片请求URL缺失仓库路径（正确路径需包含/ecommerce-product-page），导致返回404。已尝试手动设置basePath和assetPrefix、更换GitHub Action的.yml文件、修改图片导入路径（移除public前缀触发构建错误）等操作，均未解决问题。当前图片导入语句为：

import sampleImage from '/public/images/sampleImage.jpg'

解决步骤 #

1. 配置next.config.js #

在项目根目录的next.config.js中明确设置basePath、assetPrefix，并关闭Next.js图片优化（GitHub Pages不支持该功能）：

/** @type {import('next').NextConfig} */
const nextConfig = {
  basePath: '/ecommerce-product-page',
  assetPrefix: '/ecommerce-product-page/',
  images: {
    unoptimized: true,
  },
}

module.exports = nextConfig

2. 修正图片导入路径 #

Next.js中public目录是静态资源根目录，导入时无需添加/public前缀，正确导入语句应为：

import sampleImage from '/images/sampleImage.jpg'

组件中直接使用该变量即可：

<img src={sampleImage} alt="示例图片" />

如果存在硬编码的图片URL，需手动拼接basePath，可通过环境变量统一管理：

• 在.env文件中添加：

  NEXT_PUBLIC_BASE_PATH=/ecommerce-product-page
  

• 组件中使用：

  <img src={`${process.env.NEXT_PUBLIC_BASE_PATH}/images/sampleImage.jpg`} alt="示例图片" />
  

3. 检查GitHub Action配置 #

确保Action配置未覆盖basePath相关设置，推荐使用官方部署模板：

name: Deploy Next.js to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码
        uses: actions/checkout@v4
      - name: 配置Node环境
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: "npm"
      - name: 安装依赖
        run: npm install
      - name: 构建项目
        run: npm run build
      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: ./out

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: 部署到GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

4. 验证部署结果 #

部署完成后，检查图片请求URL是否包含/ecommerce-product-page前缀，例如正确路径应为https://borzoomv.github.io/ecommerce-product-page/images/sampleImage.jpg。

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