Next.js静态导出场景下如何将在线图片本地化并使用本地路径访问

Next.js 执行next export静态导出时，默认不会处理远程来源的图片，也不会将其下载到本地产物中，可按以下步骤配置实现需求： #

1. 基础必填配置 #

首先修改项目根目录的next.config.js，关闭默认的服务端图片优化，开启静态导出支持：

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Next.js 12.1+ 推荐用该配置替代命令行的next export参数
  output: 'export',
  images: {
    // 静态导出必须开启该配置，关闭Next.js自带的服务端图片优化能力
    unoptimized: true,
    // Next.js 12及之前版本配置允许的远程图片域名
    domains: ['你的远程图片来源域名，例如example.com'],
    // Next.js 13+版本推荐用remotePatterns替代domains
    // remotePatterns: [
    //   {
    //     protocol: 'https',
    //     hostname: 'example.com',
    //     pathname: '/img/**',
    //   },
    // ],
  }
}

module.exports = nextConfig

2. 远程图片本地化实现 #

完成基础配置后，还需要额外处理远程图片的下载和路径替换，可选择以下两种方案：

方案A：自定义构建脚本（无第三方依赖） #

适合图片数量不多、场景简单的项目：

• 项目根目录新建scripts/download-remote-images.js脚本，核心逻辑如下：

const fs = require('fs')
const path = require('path')
const https = require('https')
const { pipeline } = require('stream/promises')

// 自行替换为你项目中用到的所有远程图片URL，可自行扩展从接口、本地markdown文件中批量解析
const remoteImageUrls = [
  'https://example.com/img1.jpg',
  'https://example.com/img2.png'
]

const downloadDir = path.join(process.cwd(), 'public', 'images')
// 本地存储目录不存在则自动创建
if (!fs.existsSync(downloadDir)) fs.mkdirSync(downloadDir, { recursive: true })

async function downloadImage(url) {
  const filename = path.basename(url)
  const localPath = path.join(downloadDir, filename)
  // 已有缓存逻辑，已下载过的图片跳过避免重复下载
  if (fs.existsSync(localPath)) return
  await pipeline(
    https.request(url),
    fs.createWriteStream(localPath)
  )
  console.log(`下载完成：${url}`)
}

// 批量执行下载
Promise.all(remoteImageUrls.map(downloadImage)).then(() => {
  console.log('所有远程图片下载完成')
})

• 修改package.json中的构建命令，让图片下载脚本在next build之前自动执行：

{
  "scripts": {
    "prebuild": "node scripts/download-remote-images.js",
    "build": "next build"
  }
}

• 代码中引用图片时直接使用对应的本地路径即可：

import Image from 'next/image'

function Demo() {
  return <Image src="/images/img1.jpg" alt="示例图" width={800} height={600} />
}

方案B：使用第三方插件 #

适合图片数量多、需要自动匹配规则匹配远程图片的项目：

1. 安装插件：npm install next-image-export-optimizer
2. 修改next.config.js配置，引入插件：

const withExportImages = require('next-image-export-optimizer')

const nextConfig = {
  output: 'export',
  images: {
    domains: ['你的远程图片来源域名'],
  },
  exportImages: {
    // 配置需要下载的远程图片列表，也可配置规则自动匹配
    remoteImages: [
      'https://example.com/img1.jpg',
      'https://example.com/img2.png'
    ]
  }
}

module.exports = withExportImages(nextConfig)

3. 修改package.json构建命令：

{
  "scripts": {
    "build": "next build && next-image-export-optimizer"
  }
}

注意事项 #

• 如果使用App Router的next/image组件，必须为图片设置width和height属性，或者使用fill属性配合父容器定位，否则构建会报错。
• 可自行扩展下载脚本时可增加哈希命名逻辑，避免重复下载图片，提升构建速度。
  内容的提问来源于stack exchange，提问作者lemon69