ES6模块化语法在JS脚本中的导入与导出用法

一、模块导出的具体形式与用法（export）

在 ES6 模块体系中，每一个 .js 文件都被视为一个独立的模块。模块内部声明的所有变量、函数与类，默认都处于当前文件的私有作用域中，外部脚本无法直接访问。只有通过 export 关键字显式导出的内容，才能被其他模块引用。

export 语法主要分为两大家族：命名导出（Named Exports）与默认导出（Default Export）。两者在导出的数量限制、语法书写和后续导入的对应方式上存在根本差异。

1. 命名导出（Named Exports）

命名导出允许一个模块对外暴露出多个变量、函数或对象。每一个被导出的成员都保留其原本的标识符名称。命名导出主要有两种书写形式：

• 声明时直接导出：在变量声明（const、let、var）或函数、类声明前直接附加 export 关键字。
• 统一清单导出：在模块尾部使用大括号包裹需要对外暴露的标识符清单。注意这里的花括号不是对象字面量，而是专门的导出列表语法。

// utils.js
// 形式一：声明时直接导出
export const API_BASE_URL = 'https://api.example.com';
export const MAX_RETRY_COUNT = 3;

export function formatTimestamp(timestamp) {
  return new Date(timestamp).toLocaleDateString('zh-CN');
}

// 形式二：统一清单导出，并使用 as 重命名对外符号
const internalKey = 'SECRET_KEY_123';
function computeHash(data) {
  return btoa(data);
}

export {
  internalKey as apiKey,
  computeHash
};

使用命名导出的核心特征在于：导入方必须知道确切的导出名称，并使用同名变量接收，或者在导入时使用 as 别名。

2. 默认导出（Default Export）

默认导出主要用于代表该模块“最核心”或“唯一”的功能实体，例如一个类、一个主配置对象或一个核心处理函数。每个模块文件有且仅允许存在一个 export default。

// Logger.js
// 默认导出一个类
export default class Logger {
  constructor(tag) {
    this.tag = tag;
  }
  log(message) {
    console.log(`[${this.tag}] ${message}`);
  }
}

也可以默认导出一个匿名表达式、字面量或已有变量：

// config.js
const appConfig = {
  theme: 'dark',
  version: '2.4.0'
};

// 导出已有变量作为默认输出
export default appConfig;

3. 聚合与转发导出（Re-exporting）

在构建大型工具库或分层架构时，通常需要在一个入口文件（如 index.js）中集中暴露多个子模块的内容。此时可以使用转发导出语法，无需在当前模块中将它们显式导入再导出：

// components/index.js
// 转发 button.js 的默认导出为命名导出
export { default as Button } from './button.js';

// 转发 modal.js 的所有命名导出
export * from './modal.js';

// 转发特定命名导出并重命名
export { showToast as displayNotice } from './toast.js';

二、模块导入的精准匹配用法（import）

在消费模块的脚本中，通过 import 语句载入其他模块导出的功能。import 语法必须与导出方的形式保持严格对称。

1. 具名导入与花括号解构

对应命名导出，必须使用 import { 原名称 } from '路径' 的形式。如果导入的名称与当前模块中的局部变量冲突，或者名称过长，可使用 as 关键字进行重命名：

// 导入特定成员
import { API_BASE_URL, formatTimestamp } from './utils.js';

// 重命名冲突的变量名
import { apiKey as systemApiKey } from './utils.js';

2. 默认导出的无花括号导入

对应 export default，导入时绝对不能加花括号。因为默认导出本身没有强制名称，导入方可以根据业务语境自定义赋予接收变量名：

// 正确：无花括号，导入 Logger 类的默认导出，赋予自定义名称 CustomLogger
import CustomLogger from './Logger.js';

// 实例化使用
const logger = new CustomLogger('AppWorker');
logger.log('Worker 初始化完成');

3. 混合导入（同时导入默认与命名成员）

很多通用类库（例如 React 或自研工具库）既有一个默认的核心对象，又附带多个辅助命名函数。ES6 语法支持在一条 import 语句中同时提取默认导出与命名导出：

// 默认导出放在花括号之前，命名成员置于花括号内部
import EngineCore, { startEngine, stopEngine } from './engine.js';

4. 全量命名空间导入（Namespace Import）

当目标模块导出了大量命名函数，或者希望将模块作为一个独立的命名空间来调用时，可以使用 * as 命名空间名：

// 将 math.js 中所有的命名导出打包到一个 MathUtils 对象下
import * as MathUtils from './math.js';

console.log(MathUtils.PI);
console.log(MathUtils.add(5, 3));

5. 裸导入（仅触发模块副作用）

如果只需要执行目标脚本中的全局初始化逻辑、挂载补丁（Polyfill）或注入全局样式，而不关心它导出了什么内容，可以直接执行裸导入：

// 仅加载并执行 polyfills.js 内的代码，不声明任何局部接收变量
import './polyfills.js';

三、在 JS 运行环境中启用 ES6 模块的操作步骤

如果直接在一个普通的 <script> 标签或默认的 Node.js 脚本中书写 import / export，运行环境会直接抛出语法错误：SyntaxError: Cannot use import statement outside a module。这是因为宿主环境默认将 JS 代码视为传统非模块脚本（Script）。要让模块化语法生效，必须显式启用模块模式。

1. 浏览器环境下的配置步骤

在现代浏览器中，只需在 HTML 的 <script> 标签上声明 type="module" 属性：

<!-- index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>ESM 浏览器运行测试</title>
</head>
<body>
  <div id="app">加载中...</div>

  <!-- 关键：声明 type="module"，指定入口脚本 -->
  <script type="module" src="./src/main.js"></script>
</body>
</html>

声明 type="module" 后，浏览器行为会产生三个关键变化：

1. 默认开启严格模式（Strict Mode）：无需在文件顶部书写 'use strict';，模块内自动运行在严格模式下（this 默认不指向全局 window，而是 undefined）。
2. 默认延迟执行（Deferred）：模块脚本的下载不会阻塞 HTML 解析，其行为类似于普通脚本添加了 defer 属性，会在 DOM 树解析完成后、DOMContentLoaded 触发前按依赖顺序执行。
3. 遵循同源策略与 CORS 限制：模块脚本无法通过本地直接双击打开的 file:// 协议正确请求子模块，否则控制台会报跨域错误。必须通过本地 HTTP 服务器运行（例如使用 VS Code Live Server，或运行 npx serve . / python3 -m http.server）。
4. 必须书写完整扩展名：原生浏览器无法自动补全 .js 扩展名。import { add } from './math' 会导致 404，必须书写为 import { add } from './math.js'。

2. Node.js 环境下的配置步骤

Node.js 历史悠久，其早期的原生模块系统是 CommonJS（即 require / module.exports）。从 Node.js 12+ 开始对 ESM 提供了稳定支持，在 Node.js 中启用 ES6 模块主要有两种方式：

• 项目级全局启用（推荐）：在项目的 package.json 文件中增加顶层字段 "type": "module"。设置后，该目录及子目录下所有的 .js 文件都会被 Node.js 统一当做 ES6 模块解析。
• 单个文件启用：如果项目整体依然是 CommonJS，但有个别脚本需要使用 ESM，可将该文件后缀直接修改为 .mjs（Module JavaScript）。

// package.json 关键配置
{
  "name": "esm-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/main.js"
  }
}

四、核心底层机制与高频避坑指南

真正掌握 ES6 模块，不仅在于记住关键字书写，更在于理解它在 JavaScript 引擎中的运作底层。很多来自 CommonJS 或脚本时代的固有思维，往往是造成运行时隐蔽 Bug 的根源。

1. 静态解析与编译期绑定（Static Structure）

CommonJS 的 require() 是一个运行时的普通函数调用，因此你可以将它写在 if 语句内部，或者传入拼接的动态路径。

然而，ES6 的 import 是静态声明语法。在 JavaScript 代码执行之前，引擎的词法分析与模块解析器就必须构建出完整的模块依赖关系拓扑图（Module Dependency Graph）。

如果确实需要根据用户操作或运行环境动态加载模块，应使用 ES2020 引入的标准动态导入函数 import()。它返回一个 Promise，支持在任何代码块中使用：

// 条件按需动态加载模块
async function handleUserExport() {
  if (needPdfSupport) {
    // 动态 import() 返回 Promise，支持在函数内部按需触发网络下载与执行
    const { generatePdf } = await import('./pdfGenerator.js');
    generatePdf();
  }
}

2. 只读实时引用（Live Bindings）

这是 ES6 模块与 CommonJS 最本质的区别：

• CommonJS 导出的是值的拷贝：module.exports 在导出那一瞬间，将对象或基本类型复制过去。后续原模块内部修改变量，导入方持有的值不会同步更新。
• ES6 模块导出的是只读实时引用（Live Bindings）：import 进来的变量并不是一份拷贝，而是指向导出模块内部内存地址的一个只读“符号指针”。当导出模块内部更改该变量时，导入方的变量值会实时发生同步变化；但导入方自身绝不允许直接对该变量重新赋值。

// counter.js (导出模块)
export let counter = 10;
export function increment() {
  counter++; // 内部修改自身变量，完全合法
}

// app.js (导入模块)
import { counter, increment } from './counter.js';

console.log(counter); // 输出: 10
increment();
console.log(counter); // 输出: 11 (实时引用，感知到了导出方的内部变化)

// 错误尝试：
counter = 99; // 报错！TypeError: Assignment to constant variable.
// 导入方拥有的只是只读映射，无权直接修改它

3. 常见报错表现与排查方案

五、导出与导入技术选型决策与规范总结

在实际编写工程项目时，应根据业务实体的性质和团队协作规范，合理选择导出模式：

1. 工具函数集合、常量配置集：坚决使用命名导出（Named Exports）。其一，有利于现代前端构建工具（Rollup、Webpack、Vite）进行精确的 Tree-shaking 死代码消除；其二，IDE 能够提供精准的自动补全与重构重命名支持，避免团队成员各自起别名导致的语义混乱。
2. 单一职责的组件、核心服务类：采用默认导出（Default Export）。当一个文件只对外输出一个核心类或单一功能时，默认导出清晰指明了该模块的存在目的。
3. 避免过度使用 import * as：命名空间全量导入虽然省事，但往往会阻碍打包工具对未调用函数的剔除，导致最终打包体积膨胀。