Shopify应用Vite生产构建报错：require未定义问题排查

问题现象 #

• 未修改代码，本地开发运行正常，但生产构建后嵌入式页面完全无法渲染
• 浏览器控制台报错：

index-d27b9a09.js:79 Uncaught ReferenceError: require is not defined
    at index-d27b9a09.js:79:72236

排查结果 #

生产构建产物index.js中出现了此前从未有过的require语句，而浏览器环境不支持Node.js的CommonJS语法。

当前配置 #

Vite配置文件 #

import { defineConfig } from "vite";
import { dirname } from "path";
import { fileURLToPath } from "url";
import https from "https";
import react from "@vitejs/plugin-react";

if (
  process.env.npm_lifecycle_event === "build" &&
  !process.env.CI &&
  !process.env.SHOPIFY_API_KEY
) {
  console.warn(
    "\nBuilding the frontend app without an API key. The frontend build will not run without an API key. Set the SHOPIFY_API_KEY environment variable when running the build command.\n"
  );
}

const proxyOptions = {
  target: `http://127.0.0.1:${process.env.BACKEND_PORT}`,
  changeOrigin: false,
  secure: true,
  ws: false,
};

const host = process.env.HOST
  ? process.env.HOST.replace(/https?:\/\//, "")
  : "localhost";

let hmrConfig;
if (host === "localhost") {
  hmrConfig = {
    protocol: "ws",
    host: "localhost",
    port: 64999,
    clientPort: 64999,
  };
} else {
  hmrConfig = {
    protocol: "wss",
    host: host,
    port: process.env.FRONTEND_PORT,
    clientPort: 443,
  };
}

export default defineConfig({
  root: dirname(fileURLToPath(import.meta.url)),
  plugins: [react()],
  define: {
    "process.env.SHOPIFY_API_KEY": JSON.stringify(process.env.SHOPIFY_API_KEY),
  },
  resolve: {
    preserveSymlinks: true,
  },
  server: {
    host: "localhost",
    port: process.env.FRONTEND_PORT,
    hmr: hmrConfig,
    proxy: {
      "^/(\\?.*)?$": proxyOptions,
      "^/api(/|(\\?.*)?$": proxyOptions,
      "^/bundle/checkout(\\?.*)?$": proxyOptions,
    },
  },  
});

package.json依赖配置 #

{
  "name": "shopify-frontend-template-react",
  "version": "1.0.0",
  "private": true,
  "license": "UNLICENSED",
  "scripts": {
    "build": "vite build",
    "dev": "vite",
    "coverage": "vitest run --coverage"
  },
  "type": "module",
  "engines": {
    "node": ">= 12.16"
  },
  "stylelint": {
    "extends": "@shopify/stylelint-polaris"
  },
  "dependencies": {
    "@formatjs/intl-locale": "^3.3.2",
    "@formatjs/intl-localematcher": "^0.4.0",
    "@formatjs/intl-pluralrules": "^5.2.4",
    "@shopify/app-bridge": "^3.7.7",
    "@shopify/app-bridge-react": "^3.7.7",
    "@shopify/i18next-shopify": "^0.2.3",
    "@shopify/polaris": "^10.49.1",
    "@shopify/react-form": "^2.5.5",
    "@shopify/react-hooks": "^3.0.5",
    "@vitejs/plugin-react": "1.2.0",
    "dayjs": "^1.11.9",
    "i18next": "^23.1.0",
    "i18next-resources-to-backend": "^1.1.4",
    "react": "^17.0.2",
    "react-dom": "^17.0.2",
    "react-i18next": "^13.0.0",
    "react-query": "^3.34.19",
    "react-router-dom": "^6.3.0",
    "vite": "^4.3.9"
  },
  "devDependencies": {
    "@shopify/stylelint-polaris": "^12.0.0",
    "history": "^5.3.0",
    "jsdom": "^19.0.0",
    "prettier": "^2.6.0",
    "stylelint": "^15.6.1",
    "vi-fetch": "^0.6.1"
  }
}

问题成因 #

1. 依赖自动更新引入CommonJS代码：你的package.json中多数依赖使用^前缀，会自动安装次版本更新。某个依赖的新版本可能改用了CommonJS格式编写，而旧版Vite插件对这类依赖的转换处理不完善，导致生产构建时require语句残留。
2. Vite插件版本兼容性：当前使用的@vitejs/plugin-react@1.2.0是较旧版本，和Vite 4.x的兼容性不佳，对CommonJS模块的转换能力不如新版本。

解决方案 #

方案1：临时锁定依赖版本 #

• 删除node_modules和package-lock.json文件
• 将package.json中所有带^的依赖版本改为固定版本（比如@formatjs/intl-locale@^3.3.2改为@formatjs/intl-locale@3.3.2）
• 重新执行npm install后再构建

方案2：配置Vite强制转换CommonJS（推荐） #

修改Vite配置，添加CommonJS转换规则：

export default defineConfig({
  // 保留原有配置...
  optimizeDeps: {
    esbuildOptions: {
      target: 'es2020',
      format: 'esm',
    },
  },
  build: {
    commonjsOptions: {
      transformMixedEsModules: true, // 强制转换混合ES模块的CommonJS代码
      include: [/node_modules/], // 覆盖所有node_modules中的依赖
    },
    target: 'es2020',
  },
});

方案3：更新Vite插件版本 #

将@vitejs/plugin-react升级到兼容Vite 4.x的最新版本：

npm install @vitejs/plugin-react@latest --save

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