迁移CRA到Vite时，styled-components ESM文件遭CommonJS解析器抛意外令牌错误

我正在将Create React App（CRA）项目迁移至Vite，项目中使用styled-components的代码如下：

import styled from 'styled-components';

const someDiv = styled.div`...`;

执行vite build命令时触发错误：

vite v4.0.2 building for production...
✓ 51 modules transformed.
[commonjs--resolver] Unexpected token (1:167492) in /project/node_modules/styled-components/dist/styled-components.browser.esm.js
file: /project/node_modules/styled-components/dist/styled-components.browser.esm.js:1:167492
1: import{typeOf as e,isElement as t,isValidElementType as n}from"react-is";import r,{useState as o,useContext as i,useMemo as s,useEffect as a,useRef as c,createElement as u,useDebugValue as l,useLayoutEffect as d}from"react";import h from"shallowequal";import p from"@emotion/stylis";import f from"@emotion/unitless";import m from"@emotion/is-prop-valid";import y from"hoist-non-react-statics";function // ... rest of file

可见Vite的CommonJS解析器尝试处理styled-components的ESM格式文件，因文件顶部存在import语句而报错。请问：

1. 该错误的原因是什么？
2. 如何解决？
3. 为何Vite未以ESM方式导入该文件？

2023年2月7日更新：在GitHub讨论中发现，移除vite.config.ts中的define块可解决问题，但实际需要配置define时该方案并不适用。

错误原因 #

核心原因是Vite错误地将styled-components的ESM格式文件判定为CommonJS文件解析。根源在于define配置中的全局变量替换操作，破坏了Vite对模块格式的自动检测逻辑——当Vite提前替换文件中的全局变量后，会误判文件类型为CommonJS，进而用CommonJS解析器处理ESM文件，导致解析import语句时触发语法错误。

解决方法 #

如果需要保留define配置，可采用以下两种方案：

• 方案一：强制指定styled-components为ESM模块
  在vite.config.ts中通过optimizeDeps配置，明确让Vite按ESM格式处理styled-components：

  import { defineConfig } from 'vite';
  import react from '@vitejs/plugin-react';
  
  export default defineConfig({
    plugins: [react()],
    define: {
      // 你的原有define配置内容
    },
    optimizeDeps: {
      mainFields: ['module', 'main'],
      include: ['styled-components']
    }
  });
  

• 方案二：调整define配置的写法
  避免在define中替换可能干扰模块检测的全局变量，比如优先使用Vite内置的import.meta.env替代process.env这类Node.js全局变量。如果必须保留相关替换，确保替换内容是合法的JS语法，不会破坏文件的模块结构。

为何Vite未以ESM方式导入该文件 #

Vite默认会优先读取包package.json中的module字段，加载ESM格式文件。但当define配置的全局替换修改了文件内容后，Vite的模块格式检测逻辑失效，误将ESM文件识别为CommonJS文件，最终使用错误的解析器处理，导致报错。

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