解决 Vite 启动报错：Expected identifier but found 'import'

问题描述

在使用 Vite + React 开发项目时，运行 npm run dev 命令可能遭遇如下错误：

✘ [ERROR] Expected identifier but found "import"

    (define name):1:0:
      1 │ import.meta.dirname
        ╵ ~~~~~~

✘ [ERROR] Expected identifier but found "import"

    (define name):1:0:
      1 │ import.meta.filename
        ╵ ~~~~~~

✘ [ERROR] Expected identifier but found "import"

    (define name):1:0:
      1 │ import.meta.url
        ╵ ~~~~~~

failed to load config from /path/to/vite.config.js
error when starting dev server:

该错误会导致开发服务器启动失败，核心问题是 Vite 在解析 import.meta 语法时出现异常，通常由 esbuild 版本冲突引发。

原因分析

此问题由 esbuild@0.24.1 的不兼容变动引起：

1. esbuild 0.24.1 版本引入破坏性变更（详见 GitHub Issue#4010)
2. Vite 框架依赖 esbuild 处理配置文件
3. 升级 esbuild 0.24.1 后导致 Vite 配置文件解析失败

解决方案

方案一：降级 esbuild（推荐）

直接降级 esbuild 到稳定版本 0.24.0：

npm install -D esbuild@0.24.0

重新启动项目：

npm run dev

适用范围

• 所有 Vite 版本项目
• 需快速恢复开发的场景

方案二：升级 Vite 至 6.0.5+

官方已在 Vite 6.0.5 中修复此问题：

npm install vite@6.0.5
# 或安装最新版本
npm install vite@latest

版本提示

检查 package.json 确保 Vite 版本 ≥ 6.0.5：

// package.json
"devDependencies": {
  "vite": "^6.0.5"
}

方案三：包管理器依赖锁定

通过包管理器的版本锁定功能强制使用安全版本：

npm

// package.json
{
  "overrides": {
    "esbuild": "0.24.0"
  }
}

yarn

// package.json
{
  "resolutions": {
    "esbuild": "0.24.0"
  }
}

pnpm

// package.json
{
  "pnpm": {
    "overrides": {
      "esbuild": "0.24.0"
    }
  }
}

应用配置后重新安装依赖：

npm install   # 或 yarn/pnpm install

解决方案对比

方法	适用场景	维护性	操作复杂度
降级 esbuild	紧急修复	一般	简单
升级 Vite	长期项目维护	优秀	中等
包管理器锁版本	多依赖协作项目	良好	中等

附：验证流程

1. 检查当前 esbuild 版本：

npx esbuild --version

2. 如果输出为 0.24.1，执行修复措施：

npm list esbuild  # 确认依赖路径
npm install esbuild@0.24.0

3. 清理缓存后重启：

rm -rf node_modules/.vite
npm run dev

结论

1. 优先升级 Vite 到 6.0.5+ 一劳永逸
2. 紧急情况下可通过 npm install -D esbuild@0.24.0 快速恢复开发
3. 团队协作项目推荐使用包管理器版本锁定

官方问题追踪：Vite#19018 | esbuild#4012