【Next.js】如何解决 Invalid src prop 错误？外部图像加载详解

Next.js 是现代 Web 开发中广泛使用的 React 框架，以其高性能和灵活性深受开发者喜爱。在开发过程中，很多人会遇到 next/image 组件加载外部图片时报错的问题。本文将详细解析 Invalid src prop 错误的成因，并一步步指导你如何解决该问题。

---

一、问题背景

1. 什么是 next/image？

next/image 是 Next.js 提供的一个内置组件，用于优化图像加载。它具有以下特点：

• 自动进行图片大小调整和格式优化。
• 支持懒加载，提升页面性能。
• 在构建阶段或运行时，通过 CDN 实现快速加载。

但是，为了安全和性能，next/image 对外部图片的使用进行了限制。开发者必须显式地配置允许加载的图片源。

2. 错误的具体表现

当尝试通过 next/image 加载外部图片时，如果未正确配置图片域名，可能会看到如下错误：

Error: Invalid src prop (https://images.pexels.com/photos/2888150/pexels-photo-2888150.jpeg?auto=compress&cs=tinysrgb&w=1200) on `next/image`, hostname "images.pexels.com" is not configured under images in your `next.config.js`
See more info: https://nextjs.org/docs/messages/next-image-unconfigured-host

3. 为什么会报错？

next/image 的设计初衷是增强图片加载的安全性和优化能力。默认情况下，next/image 只允许加载来自本地项目 /public 目录的图片。如果需要加载外部图片，需要显式地在配置文件中声明允许的图片域名。

---

二、解决方法

1. 在 next.config.js 中配置允许的域名

第一步：找到或创建 next.config.js

在项目根目录下找到 next.config.js 文件。如果项目中没有这个文件，可以新建一个。

第二步：添加 images.domains 配置

将需要加载图片的域名（如 images.pexels.com）添加到 images.domains 数组中。例如：

/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['images.pexels.com'], // 在这里添加你的图片域名
  },
};

module.exports = nextConfig;

第三步：重启开发服务器

修改配置文件后，需要重启 Next.js 开发服务器，才能使更改生效：

npm run dev
# 或者
yarn dev

---

2. 测试外部图片是否正常加载

在组件中使用 next/image 加载外部图片，例如：

import Image from 'next/image';

export default function Example() {
  return (
    <Image
      src="https://images.pexels.com/photos/2888150/pexels-photo-2888150.jpeg?auto=compress&cs=tinysrgb&w=1200"
      alt="Example"
      width={800}
      height={600}
    />
  );
}

如果配置正确，图片应该能够正常加载，不会再报错。

---

三、深入解析

1. 为什么需要配置域名？

next/image 使用了优化图像加载的机制，这包括代理和缓存外部图片。为了避免加载恶意或不受信任的图片来源，Next.js 要求开发者手动指定可信任的域名。

2. 支持哪些外部图片来源？

next/image 支持以下两种外部图片来源：

• 固定域名：通过 images.domains 指定。
• 动态路径：通过配置自定义加载器（见下文）。

---

四、高级配置

1. 加载动态图片

如果外部图片的域名是动态生成的，无法提前知道完整的域名列表，可以使用自定义加载器：

import Image from 'next/image';

const myLoader = ({ src }) => {
  return `https://example.com/${src}`;
};

export default function MyImage() {
  return (
    <Image
      loader={myLoader}
      src="my-image.jpg"
      alt="Dynamic Image"
      width={800}
      height={600}
    />
  );
}

在这个例子中，myLoader 函数生成了图片的完整 URL，从而避免直接依赖 images.domains。

---

2. 开启远程图像优化

对于外部图片，Next.js 默认会尝试进行优化。如果你想关闭优化（比如为了提升加载速度），可以在配置文件中设置：

const nextConfig = {
  images: {
    unoptimized: true, // 关闭图片优化
  },
};

module.exports = nextConfig;

---

五、常见问题及解决方法

1. 图片加载失败，提示 404 错误

原因：图片路径不正确，或者目标服务器返回了错误。 解决方法：

• 检查 src 是否是完整的图片 URL。
• 使用浏览器直接访问图片 URL，确认它是否有效。

2. 多个域名的图片需要加载

解决方法：将所有需要加载图片的域名添加到 images.domains 中。例如：

const nextConfig = {
  images: {
    domains: ['images.pexels.com', 'cdn.example.com'],
  },
};

3. 性能优化提示：外部图片未被优化

解决方法：确保你的服务器支持图片优化。如果没有优化需求，可以使用 unoptimized: true 关闭优化功能。

---

六、总结

next/image 是 Next.js 的强大功能之一，为开发者提供了便捷的图像加载优化工具。通过正确配置 next.config.js，你可以在项目中安全高效地加载外部图片。

当遇到 Invalid src prop 错误时：

1. 确认图片的域名是否已添加到 images.domains。
2. 配置好后重启开发服务器。
3. 测试图片是否加载正常。

希望这篇文章能帮助你理解并解决 next/image 的常见问题，为你的 Next.js 项目打造更高效的用户体验！

推荐：

• JavaScript
• react
• vue

---