错误：对 URL '...' 的图像优化失败，状态码 500。内部错误：sharp 未安装。
Error: Image optimization failed for URL '...' with status 500. Internal error: sharp is not installed.
ID: nextjs/image-optimization-internal-server-error
版本兼容性
| 版本 | 状态 | 引入 | 弃用 | 备注 |
|---|---|---|---|---|
| 13.4.0 | active | — | — | — |
| 13.5.0 | active | — | — | — |
| 14.0.0 | active | — | — | — |
| 14.2.0 | active | — | — | — |
| 15.0.0 | active | — | — | — |
根因分析
Next.js 图像优化依赖 'sharp' 库进行服务器端图像处理。当 sharp 缺失或安装失败（例如在某些架构或无服务器环境中）时，优化端点返回 500 错误。
English
Next.js image optimization relies on the 'sharp' library for server-side image processing. When sharp is missing or fails to install (e.g., on certain architectures or serverless environments), the optimization endpoint returns a 500 error.
官方文档
https://nextjs.org/docs/app/api-reference/components/image#optimization解决方案
-
Install sharp explicitly as a production dependency: npm install sharp@latest. Ensure your deployment platform supports sharp (e.g., Vercel, Netlify). For serverless, use next.config.js: experimental: { optimizePackageImports: ['sharp'] }. -
If sharp cannot be installed, set images.unoptimized: true in next.config.js to disable all image optimization globally, or use a third-party image CDN provider configured via images.loader.
无效尝试
常见但无效的做法:
-
Reinstalling sharp with npm install sharp without specifying the correct platform binary
60% 失败
The default installation may try to build from source, failing on systems without C++ build tools. It's better to use --ignore-scripts or install platform-specific binaries.
-
Setting unoptimized: true on every Image component as a global workaround
30% 失败
This disables all image optimization, leading to large unoptimized images, slower page loads, and potential layout shifts. It's a performance regression.