Bun/Vite在GitHub Actions/Ubuntu构建失败，报‘undefined’错误如何排查？

本地Mac环境执行bunx --bun vite build可正常完成生产构建，输出如下：

vite v5.4.2 building for production...
✓ 2951 modules transformed.
dist/index.html                     1.03 kB │ gzip:   0.56 kB
dist/assets/index-BifuYEoc.css     38.29 kB │ gzip:   8.03 kB
dist/assets/index-BG4aLjCM.js   3,571.02 kB │ gzip: 649.00 kB
✓ built in 3.08s

但在GitHub Actions工作流中执行该命令时，构建失败并提示“undefined”错误，输出如下：

vite v5.4.2 building for production...
transforming...
✓ 347 modules transformed.
x Build failed in 3.12s
error during build:
undefined
error: script "build" exited with code 1
Error: Process completed with exit code 1.

唯一已知变更为新增了vite.config.ts配置文件，内容如下：

import path from "path";
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import graphqlLoader from "vite-plugin-graphql-loader";
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [react(), graphqlLoader(), tsconfigPaths()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, './src')
    },
  }
});

以下是具体排查步骤：

• 开启Vite详细调试日志
  在GitHub Actions的构建命令前添加环境变量，修改为：DEBUG=vite:* bunx --bun vite build，这样能输出Vite构建过程中的所有调试信息，定位到具体抛出undefined错误的环节。

• 校验依赖安装一致性
  确保CI环境依赖与本地完全一致，在构建步骤前执行bun install --frozen-lockfile，强制使用本地锁定的依赖版本，避免因依赖版本差异导致的兼容性问题。同时检查新增的三个插件（@vitejs/plugin-react、vite-plugin-graphql-loader、vite-tsconfig-paths）是否都被正确安装。

• 排查tsconfig-paths插件问题
  先暂时从vite.config.ts中移除tsconfigPaths()插件，重新运行CI构建。如果构建成功，说明该插件存在问题：

  • 检查项目根目录的tsconfig.json，确认baseUrl和paths配置正确，且CI环境能正确解析这些路径；
  • 尝试升级vite-tsconfig-paths插件版本，确保与Vite 5.4.2兼容。

• 修复跨平台路径解析问题
  本地是Mac（Unix系统），CI环境可能是Ubuntu或Windows，path.resolve生成的路径可能存在跨平台兼容性问题。可以将别名配置修改为两种更兼容的写法：

  // 写法1：使用path.join
  '@': path.join(__dirname, 'src')
  // 写法2：直接使用相对路径（Vite会自动解析）
  '@': './src'
  

  修改后重新运行CI构建，验证是否解决问题。

• 排查vite-plugin-graphql-loader插件问题
  暂时移除graphqlLoader()插件，重新执行CI构建。如果构建成功，说明该插件存在兼容性问题：

  • 检查项目中.graphql文件是否在CI环境中存在，且路径正确；
  • 升级vite-plugin-graphql-loader版本，确保与Vite 5.4.2兼容；
  • 确认CI环境中是否安装了graphql核心依赖，部分插件需要依赖它才能正常工作。

• 对齐Bun和Vite版本
  确认GitHub Actions中使用的Bun版本与本地一致，不同版本的Bun对Vite的支持可能存在差异。可以在CI工作流中指定Bun版本，例如使用setup-bun action时添加version: "你的本地Bun版本号"。

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