Webpack 5（TerserPlugin）报错：Import语句只能出现在顶级作用域

问题重现 #

生产构建时TerserPlugin抛出错误：

cart-ts.js from Terser plugin
"Import" statement may only appear at the top level [cart-ts.js:33904,0]
    at js_error (<redacted>\node_modules\terser\dist\bundle.min.js:549:11)
    at TreeWalker.visit (<redacted>\node_modules\terser\dist\bundle.min.js:11766:13)
    at TreeWalker._visit (<redacted>\node_modules\terser\dist\bundle.min.js:6717:24)
    at AST_Import._walk (<redacted>\node_modules\terser\dist\bundle.min.js:5129:28)
    at walk_body (<redacted>\node_modules\terser\dist\bundle.min.js:3876:17)
    at AST_Function.<anonymous> (<redacted>\node_modules\terser\dist\bundle.min.js:4375:17)
    at <redacted>\node_modules\terser\dist\bundle.min.js:6718:21
    at TreeWalker.visit (<redacted>\node_modules\terser\dist\bundle.min.js:11668:13)
    at TreeWalker._visit (<redacted>\node_modules\terser\dist\bundle.min.js:6717:24)
    at AST_Function._walk (<redacted>\node_modules\terser\dist\bundle.min.js:4369:28)

webpack 5.90.3 compiled with 1 error in 77388 ms

已配置TerserPlugin启用ES2023和模块模式：

optimization: {
    minimizer: [
        new TerserPlugin({
            terserOptions: {
                ecma: 2023,
                module: true
            }
        })
    ]
}

核心原因 #

虽然开启了module: true，但Terser仍检测到代码中存在非顶层的静态import语句（注意：动态import()函数不会触发该错误，仅静态import ... from ...会触发），或是Webpack打包输出的代码不符合ES模块规范，导致Terser处理时判定语法违规。

解决方案（无需Babel） #

1. 排查代码中的静态import位置

全局搜索项目中的import关键字，确保所有import ... from ...语句都放在文件的最顶层，不要嵌套在函数、条件判断、循环等代码块内部：

• 错误示例：

function init() {
  import { formatPrice } from './utils'; // 静态import不能在函数内
}

• 正确示例：

import { formatPrice } from './utils'; // 静态import必须在顶层

function init() {
  import('some-dynamic-module').then(...) // 动态import可正常使用
}

2. 完善TerserPlugin配置

补充toplevel、compress.module和mangle.module选项，确保Terser完全按照ES模块规则处理代码：

optimization: {
    minimizer: [
        new TerserPlugin({
            terserOptions: {
                ecma: 2023,
                module: true,
                toplevel: true, // 启用顶层作用域优化，适配ES模块
                compress: {
                    module: true, // 压缩时识别ES模块语法
                    ecma: 2023
                },
                mangle: {
                    module: true // 混淆时保留ES模块的导出/导入名称
                }
            }
        })
    ]
}

3. 确保Webpack正确识别ES模块

在module.rules中为TypeScript文件明确设置type: 'module'，让Webpack以ES模块规则处理输入输出：

module: {
    rules: [
        {
            test: /\.ts$/,
            use: 'ts-loader',
            exclude: /node_modules/,
            type: 'module' // 标记为ES模块
        }
    ]
}

同时检查tsconfig.json，确保module字段设置为ESNext或ES2020+：

{
  "compilerOptions": {
    "module": "ESNext",
    "target": "ES2023"
  }
}

4. 升级依赖版本

旧版本的TerserPlugin或Terser可能对ES2023模块语法支持不完善，升级到最新版：

npm install terser-webpack-plugin@latest terser@latest

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