Next.js加载本地PNG/JPG图片失败问题求助

问题现象 #

• 从@/assets/img目录导入PNG图片使用next/image组件，终端报fetch失败，请求URL为http://localhost:3000/_next/image?url=%2F_next%2Fstatic%2Fmedia%2Fmy-image.f4be41c5.png&w=750&q=75
• 将JPG图片放入public/img目录，通过路径/img/my-image.jpg加载，同样报fetch失败，请求URL为http://localhost:3000/_next/image?url=%2Fimg%2Fmy-image.jpg&w=750&q=75
• 但从assets文件夹导入SVG文件可正常加载，请求URL为http://localhost:3000/_next/static/media/my-image.308008ef.svg

常见原因及解决方法 #

1. 未指定宽高（Next.js 13+ App Router场景） #

Next.js 13+的App Router模式下，next/image组件必须明确指定width和height属性，或者使用fill配合父容器定位——SVG作为矢量图不受此限制，所以能正常加载。

解决示例：

// 方式1：直接指定宽高
import Image from "next/image";
import MyImage from "@/assets/img/my-image.png";

export default function Comp(){
  return <Image src={MyImage} width={372} height={268} alt="我的图片" />
}

// 方式2：使用fill属性（需给父元素设置relative定位）
import Image from "next/image";
import MyImage from "@/assets/img/my-image.png";

export default function Comp(){
  return (
    <div style={{position: 'relative', width: 372, height: 268}}>
      <Image src={MyImage} fill alt="我的图片" />
    </div>
  )
}

2. 图片路径或命名异常 #

• 文件名包含空格、中文、特殊符号，会导致Next.js静态资源解析失败
• 文件扩展名大小写不匹配（比如实际是.PNG，代码里写.png），部分系统下会出现解析问题

解决方法：把文件名改成小写字母、数字、连字符/下划线组合，确保扩展名和实际文件一致。

3. 静态资源配置缺失 #

如果是App Router模式，需要在next.config.js中配置images.remotePatterns允许localhost的资源请求；Pages Router模式则配置images.domains。

修改next.config.js：

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    // App Router用remotePatterns
    remotePatterns: [
      {
        protocol: 'http',
        hostname: 'localhost',
        port: '3000',
        pathname: '/**',
      },
    ],
    // Pages Router用domains
    // domains: ['localhost'],
  },
}

module.exports = nextConfig

4. 缓存残留导致加载异常 #

本地开发时的旧构建缓存可能干扰资源加载，清空缓存再重新启动即可：

• 删除.next文件夹，执行rm -rf .next && npm run dev（Windows系统用rd /s /q .next && npm run dev）
• 用浏览器隐身窗口测试，避免浏览器缓存影响

5. 模块路径解析错误 #

检查tsconfig.json或jsconfig.json中的paths配置，确保@/assets指向正确的目录：

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./*"]
    }
  }
}

如果路径映射错误，会导致图片导入后解析出的URL异常。

验证步骤 #

• 直接访问图片的原始URL：比如PNG的原始地址是http://localhost:3000/_next/static/media/my-image.f4be41c5.png，JPG的是http://localhost:3000/img/my-image.jpg，如果直接访问也404，说明资源本身没被正确打包或放置
• 查看.next/static/media目录下是否存在目标PNG文件，public/img目录下是否存在目标JPG文件

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