Vite 6 升级后 `import.meta` 语法错误的解决方案

问题背景

在使用 Vite 构建 React 组件为独立 JavaScript 文件时，从 Vite 5 升级到 Vite 6 后出现了 SyntaxError: Cannot use 'import.meta' outside a module 的错误。这个问题特别发生在将 React 组件打包为 Web Components 的场景中。

问题分析

该错误的根本原因是 Vite 6 对插件系统的处理方式进行了调整。在 Vite 5 及以下版本中，Vite 特定的插件钩子会被意外地应用于 build.rollupOptions.plugins 中的插件。然而，从 Vite 6 开始，build.rollupOptions.plugins 只应该包含纯粹的 Rollup 插件。

具体到案例中，开发者错误地将 @vitejs/plugin-react 放在了 build.rollupOptions.plugins 数组中，而不是正确的 plugins 配置项中。这导致 Vite 6 不再处理该插件的 Vite 特定功能，从而使得 import.meta 语法没有被正确转换。

解决方案

正确的配置方式是将 Vite 插件放在顶层的 plugins 选项中，而不是 build.rollupOptions.plugins 中。修改后的构建配置应该如下：

await build({
  appType: "custom",
  publicDir: false,
  css: { modules: { scopeBehaviour: "local", exportGlobals: false } },
  plugins: [
    react(), // 将 Vite 插件移到这里
    styleWrapper({ iife: true })
  ],
  build: {
    cssCodeSplit: false,
    watch: false,
    minify: true,
    sourcemap: false,
    cssMinify: true,
    outDir: "dist",
    rollupOptions: {
      input: inputFile,
      external: ["react", "react-dom"],
      output: {
        entryFileNames: (chunkInfo) =>
          `webcomponents/${chunkInfo.name.replace(".entry", "")}.js`,
        noConflict: true,
        globals: {
          react: "React",
          "react-dom": "ReactDOM",
        },
      },
      plugins: [
        // 这里只保留 Rollup 插件
        typescript({ noEmit: true, allowImportingTsExtensions: true }),
        externalGlobals({
          react: "React",
          "react-dom": "ReactDOM",
        }),
      ],
    },
    emptyOutDir: false,
  },
  configFile: false,
});

技术原理

Vite 的插件系统分为两类：

1. Vite 插件：处理 Vite 特有的功能，如 HMR、CSS 处理等
2. Rollup 插件：处理底层的模块打包逻辑

在 Vite 6 中，这种区分变得更加严格。Vite 插件必须放在顶层的 plugins 选项中才能正常工作，而 Rollup 插件则应该放在 build.rollupOptions.plugins 中。这种分离使得构建过程更加清晰，也避免了潜在的冲突。

最佳实践

1. 仔细区分 Vite 插件和 Rollup 插件
2. 查阅插件文档确认其类型
3. 在升级 Vite 版本时，特别注意构建配置的变化
4. 对于复杂的构建场景，考虑分步测试验证配置

通过遵循这些原则，可以避免类似的问题，并确保构建过程的稳定性。