大网数据广告活动
Web 标准与前端开发

SyntaxError: import declarations may only appear at top level of a module

· 52CE 我爱测

The JavaScript exception "import declarations may only appear at top level of a module" occurs when an import declaration is not at the top level of a module. This might be because the import declaration is nested in other constructs (functions, blocks, etc.), or more often becau

The JavaScript exception "import declarations may only appear at top level of a module" occurs when an import declaration is not at the top level of a module. This might be because the import declaration is nested in other constructs (functions, blocks, etc.), or more often because the current file is not treated as a module.

Message

SyntaxError: Cannot use import statement outside a module (V8-based)
SyntaxError: import declarations may only appear at top level of a module (Firefox)
SyntaxError: Unexpected identifier 'x'. import call expects one or two arguments. (Safari)

Error type

SyntaxError

What went wrong?

You may have an import declaration that's nested in another construct, such as a function or a block. The import declaration must be at the top level of the module. If you want to conditionally import a module, or lazily import it on demand, use dynamic import instead.

If the import is already at the top level of the code, it may be because the file is not interpreted as a module. Runtimes require external hints to determine whether a file is a module or not, and here are several ways to provide such hints:

  • If the file is directly loaded from HTML, make sure the <script> tag has the type="module" attribute.
  • If the file is run in Node, make sure either the file has the .mjs extension, or the closest package.json file has the "type": "module" field.
  • If the file is run as a worker, make sure you call the Worker() constructor with the type: "module" option.
  • Import this file from another module.

One other cause might be when you are writing import with a compiler (such as TypeScript) and you accidentally ran the source file. Since import declarations usually appear at the very start of the program, they are the first thing the parser sees and then complains about. Make sure to compile the source file and execute the compiled file instead.

Examples

Conditional imports

You cannot use import inside other constructs, like you might do in Python.

if (writeOutput) {
  import fs from "fs"; // SyntaxError
}

Either move the import to the top level, or use dynamic import.

if (writeOutput) {
  import("fs").then((fs) => {
    // use fs
  });
}

Importing in a non-module script

If you are loading the script from HTML, make sure to add the type="module" attribute to the <script> tag.

<script type="module" src="main.js"></script>

If for some reason you cannot migrate the script to a module, you can use dynamic import.

async function main() {
  const myModule = await import("./my-module.js");
  // use myModule
}

main();

See also

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。