Next.js部署GitHub Pages执行next export报错图片加载器不兼容怎么办

Next.js 内置的默认图片优化能力依赖服务端运行环境或Vercel平台的托管能力，而next export会将项目导出为完全无服务端依赖的纯静态资源包，没有运行环境支持默认的图片优化逻辑，因此触发报错。

loader是next/image组件开放的自定义图片URL生成接口，你可以通过该属性自定义图片资源的路径拼接规则，完全替代Next.js默认的、依赖服务端的优化路径生成逻辑，让图片组件在纯静态导出场景下也能正常生成可用的资源地址。

方案1：逐个组件配置（适合少量图片的场景） #

1. 先定义自定义loader函数，规则匹配你的图片存放路径：

// 示例：所有图片存放在项目public/images目录下
const customLoader = ({ src, width, quality }) => {
  // 若GitHub Pages部署在子路径（仓库名不是<用户名>.github.io），需要在路径前加仓库名前缀，如`/my-repo/images/${src}`
  return `/images/${src}?w=${width}&q=${quality || 75}`
}

2. 在所有用到next/image的位置传入loader，并添加unoptimized属性关闭默认优化：

import Image from 'next/image'

function DemoComponent() {
  return (
    <Image
      loader={customLoader}
      src="demo.png"
      alt="演示图片"
      width={800}
      height={600}
      unoptimized
    />
  )
}

方案2：全局配置（适合大量图片的场景，不需要逐个组件传loader） #

1. 单独新建loader文件，比如utils/imageLoader.js，写入自定义loader逻辑：

// utils/imageLoader.js
export default function customLoader({ src, width, quality }) {
  return `/images/${src}?w=${width}&q=${quality || 75}`
}

2. 修改项目根目录的next.config.js配置，指定全局loader规则：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Next 12.3+版本推荐用该配置替代原生的next export命令
  output: 'export',
  images: {
    loader: 'custom',
    loaderFile: './utils/imageLoader.js',
    // 完全关闭默认优化逻辑，适配静态导出场景
    unoptimized: true
  }
}

module.exports = nextConfig

• 所有用到的本地图片需要提前放到项目的public目录下，确保导出静态资源时图片会被一同打包到输出目录
• 若你的GitHub Pages部署在子路径下，需要在loader路径中添加仓库名作为前缀，或在next.config.js中配置basePath参数，避免图片加载404

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