部署在Git Pages的NextJS应用无法加载外部图片如何解决？

核心原因 #

Next.js的Image组件出于安全考虑，生产环境下会限制未被许可的外部图片源，必须显式配置允许的域名/规则才能加载，这是导致你在Git Pages上无法显示外部图片（仅显示替代文本）的主要原因。

具体解决步骤 #

1. 修正next.config.js的图片源配置 #

首先确认配置文件名是next.config.js（注意不是你提到的next.config.file，文件名错误会导致配置不生效），然后根据你的Next.js版本添加对应配置：

推荐配置（Next.js 12.3+）：使用remotePatterns

这种方式支持更灵活的路径匹配：

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'picsum.photos',
        pathname: '/**',
      },
    ],
  },
  // 关键：Git Pages只能托管静态文件，必须开启静态导出
  output: 'export',
}

module.exports = nextConfig

兼容旧版本：使用domains

如果你的Next.js版本低于12.3，直接添加允许的域名：

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['picsum.photos'],
  },
  output: 'export',
}

module.exports = nextConfig

注意：修改配置后，必须重新执行next build && next export生成静态产物，再将out目录下的文件推送到Git Pages仓库完成部署。

2. 验证静态导出流程 #

Git Pages仅支持静态资源托管，确保你的部署流程是：

1. 执行next build构建应用
2. 执行next export生成静态文件到out目录
3. 将out目录下的所有文件推送到Git Pages的对应分支（通常是gh-pages）

3. 排查组件使用问题 #

如果配置后仍无法加载，可暂时改用原生<img>标签测试，排除Next.jsImage组件的问题：

<img src="https://picsum.photos/200/300" alt="示例图片" width={200} height={300} />

如果原生标签能显示图片，说明问题出在Image组件的配置上，检查next.config.js是否存在语法错误（比如逗号遗漏、括号不匹配）。

4. 查看浏览器错误日志 #

打开Chrome开发者工具（F12）的Console标签，查看具体错误：

• 若出现Invalid src prop类错误：说明图片源配置未生效，需重新构建部署；
• 若出现CORS相关错误：虽然picsum.photos默认允许跨域，但可尝试在图片链接后添加?v=1等参数强制刷新缓存。

常见误区 #

• 配置文件名拼写错误：必须是next.config.js，不能写成next.config.file；
• 未推送正确的文件：要推送out目录的静态产物，而非项目源码；
• 忽略output: 'export'配置：Next.js 13+必须添加该配置才能生成兼容Git Pages的静态文件。

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