Nuxt3中Nuxt/Image模块生产环境图片加载失败求助

核心问题原因 #

sharp是依赖系统架构的二进制模块，本地（如Windows/macOS）构建生成的二进制文件无法在Linux（Ubuntu）环境运行，导致服务器上找不到对应sharp-linux-x64.node文件，进而触发IPX服务报错。

服务器端关键解决步骤 #

1. 清理残留依赖与构建产物 #

先删除服务器上的本地环境残留文件，避免干扰重新安装：

rm -rf node_modules .output package-lock.json

2. 针对Ubuntu环境重新安装依赖 #

在服务器上执行安装命令，强制sharp适配当前Linux x64架构编译：

npm install --platform=linux --arch=x64

若使用pnpm或yarn，对应命令如下：

# pnpm
pnpm install --os=linux --cpu=x64
# yarn
yarn install --ignore-platform && npm rebuild sharp --platform=linux --arch=x64

3. 在服务器本地完成项目构建 #

禁止直接上传本地构建的.output目录，必须在Ubuntu服务器上执行构建命令：

npm run build

4. 安装sharp所需系统依赖（若仍报错） #

如果执行上述步骤后sharp仍无法正常工作，需安装Ubuntu系统层面的依赖库：

apt-get update && apt-get install -y libvips-dev libglib2.0-0

5. 验证sharp安装状态 #

安装完成后，执行以下命令确认sharp是否正常：

npx sharp --version

输出版本号则说明安装成功；若仍报错，重复执行步骤2的依赖安装命令。

可选：调整Nuxt Image配置（排查用） #

如果问题持续，可在nuxt.config.ts中明确指定IPX使用sharp：

export default defineNuxtConfig({
  // ...其他原有配置
  image: {
    ipx: {
      sharp: true
    }
  }
})

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