Vite项目Netlify构建失败（本地构建正常）求助

问题回顾 #

本地执行npm run build可正常完成构建，但Netlify构建main@HEAD分支时失败，提示Failed during stage 'building site': Build script returned non-zero exit code: 2。

排查步骤与解决方案 #

1. 获取完整构建日志 #

你提供的Netlify日志仅显示到初始化阶段，未包含vite build的执行过程——这是定位问题的核心依据。请登录Netlify控制台，找到对应构建任务的完整日志，查看Starting build script之后的具体报错信息（比如资源缺失、语法错误、依赖冲突等）。

2. 锁定Vite版本消除环境差异 #

本地package.json中Vite版本为^5.0.10（允许安装5.x系列最新版本），而Netlify上实际安装的是5.2.11，版本差异可能导致构建行为不一致：

• 修改package.json中Vite的版本为固定值：

  "devDependencies": {
    "@vitejs/plugin-vue": "^4.5.2",
    "vite": "5.0.10"
  }
  

• 执行npm install更新package-lock.json，将修改推送到仓库后重新触发Netlify构建。

3. 检查资源路径大小写一致性 #

本地Windows系统不区分文件路径大小写，但Netlify运行在Linux环境下，路径严格区分大小写：

• 检查所有资源引用（如src/images/categoriesback.png）的路径与实际文件名的大小写是否完全匹配，修正不一致的地方。

4. 使用npm ci确保依赖安装一致性 #

npm ci会严格按照package-lock.json的依赖版本安装，避免自动升级导致的版本问题：

• 修改Netlify构建命令为：

  npm ci && npm run build
  

5. 忽略Lottie的Eval警告（若日志显示相关错误） #

本地构建中Lottie的eval使用仅为警告，但Netlify可能将其视为错误终止构建。在vite.config.js中添加配置忽略该警告：

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

export default defineConfig({
  plugins: [vue()],
  build: {
    rollupOptions: {
      onwarn(warning, warn) {
        if (warning.code === 'EVAL') return;
        warn(warning);
      }
    }
  }
})

6. 检查环境变量是否缺失 #

若项目中使用了环境变量（如API地址、密钥等），本地配置但Netlify未设置时会导致构建失败：

• 在Netlify控制台的Site settings > Environment variables中添加项目所需的所有环境变量。

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