Next.js 14在Linux服务器导入AVIF图片报错求助

问题描述 #

在使用Next.js 14导入AVIF格式图片时出现报错，导入代码如下：

import promoImage2 from "public/promo-2.avif"; 
// import promoImage2 from "@/assets/promo-2.avif"; // 也曾尝试从assets文件夹加载

报错信息：

@/components/promo-item:14
Error: Image import "public/promo-2.avif" is not a valid image file. The image may be corrupted or an unsupported format.

该图片未损坏，在MacOS、Windows（同版本Node.js）及Node.js 18.14.0的Docker环境中均可正常构建运行，但仅在Debian Linux服务器上出现此错误。

服务器环境信息 #

next info:

Operating System:
  Platform: linux
  Arch: x64
  Version: #1 SMP Debian 5.10.92-1 (2022-01-18)
Binaries:
  Node: 18.14.0
  npm: 9.3.1
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 14.0.3
  eslint-config-next: 14.0.3
  react: 18.2.0
  react-dom: 18.2.0
  typescript: 5.3.2
Next.js Config:
  output: N/A

问题原因分析 #

1. 系统缺少AVIF处理依赖库：Next.js处理AVIF图片依赖底层系统解码库，Debian 11（5.10内核）默认未安装libavif相关组件，导致图片校验失败。
2. sharp库编译缺失AVIF支持：Next.js的图片优化依赖sharp模块，若sharp安装时未检测到系统AVIF库，会自动禁用AVIF解码功能，引发格式不支持报错。
3. 图片编码兼容性问题：部分AVIF图片采用的编码变种在Linux系统的解码库中未被支持，导致校验不通过。

解决方案 #

1. 安装系统级AVIF依赖库 #

在Debian服务器上执行以下命令，安装AVIF处理所需的系统库：

sudo apt update && sudo apt install libavif-dev libavif-tools

安装完成后，删除node_modules和package-lock.json，重新执行npm install后再构建项目。

2. 重新编译sharp库 #

强制重新安装sharp，确保其在当前系统环境下编译并启用AVIF支持：

rm -rf node_modules/sharp
npm install sharp --force

3. 重新编码AVIF图片 #

使用系统安装的avifenc工具重新编码图片，生成兼容性更好的AVIF文件：

avifenc promo-2.avif promo-2-reencoded.avif

替换原图片后重新尝试构建。

4. 配置Webpack绕过Next.js图片校验（临时方案） #

修改next.config.js，添加自定义Webpack规则直接处理AVIF文件，跳过Next.js内置的图片格式校验：

/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config) => {
    // 添加AVIF文件处理规则
    config.module.rules.push({
      test: /\.avif$/i,
      use: [
        {
          loader: 'file-loader',
          options: {
            name: '[name].[hash].[ext]',
            outputPath: 'static/images/',
          },
        },
      ],
    });
    return config;
  },
};

module.exports = nextConfig;

此方法需确保已安装file-loader：执行npm install file-loader --save-dev。

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