JavaScript模块化编程实例：ES Module导入导出实战

一、为什么现代JavaScript必须掌握ES Module

早期的JavaScript缺乏原生的模块系统，开发者只能依靠自执行函数（IIFE）结合全局对象来隔离作用域，极易发生命名冲突并导致全局污染。此后Node.js生态广泛普及了CommonJS规范（即 module.exports 与 require()），社区也涌现了AMD、CMD等方案。但CommonJS是面向服务器端运行时的同步加载机制，无法在浏览器环境中天然高效运行，且其动态求值的特性限制了打包工具做静态依赖分析。

ECMAScript 6（ES2015）正式推出了官方规范ES Module。与CommonJS不同，ES Module具有静态结构特性，所有的依赖关系必须在代码运行前的编译解析阶段确定。这不仅让依赖关系完全透明，还天然支持了树摇优化（Tree-shaking），能够在构建阶段安全移除未被使用的多余代码，大幅降低前端包体积。

图1：ES Module 静态编译解析与 CommonJS 动态加载底层机制全景对比

二、导出（export）实战：4 种核心导出方式

在ESM中，模块是一个独立的文件，文件内声明的变量、函数、类默认均处于私有模块作用域中。要对外开放能力，必须使用 export 关键字。ESM提供了命名导出、统一列表导出、默认导出以及聚合导出四种常用模式。

1. 命名导出（Named Exports）

命名导出适合用于一个模块需要对外提供多个独立工具函数或配置常量的场景。第一种方式是在声明变量或函数时直接在前面添加 export 关键字：

// utils/math.js
// 1. 声明时直接命名导出
export const PI = 3.1415926535;

export function add(a, b) {
  return a + b;
}

export function subtract(a, b) {
  return a - b;
}

第二种方式是先在模块内部定义好所有的业务逻辑，最后在文件底部使用花括号进行统一列表导出。这种方式结构更工整，利于统一查看当前模块对外暴露的API清单：

// utils/format.js
const DEFAULT_LOCALE = 'zh-CN';

function formatCurrency(amount) {
  return `¥${Number(amount).toFixed(2)}`;
}

function formatDate(date) {
  return new Intl.DateTimeFormat(DEFAULT_LOCALE).format(date);
}

// 2. 统一列表导出（注意此处并非对象字面量，而是导出语法清单）
export { DEFAULT_LOCALE, formatCurrency, formatDate };

2. 重命名导出（Renaming Exports）

如果模块内部的函数名过长或容易与外部业务命名产生歧义，可以使用 as 关键字在导出时为其指定对外别名：

function calculateStandardDeviation(dataset) {
  // 复杂算法计算过程
  return Math.sqrt(dataset.reduce((acc, val) => acc + val, 0) / dataset.length);
}

// 导出时重命名为简写别名 stdDev
export { calculateStandardDeviation as stdDev };

3. 默认导出（Default Export）

当一个模块的核心职责非常明确，对外主要输出一个主类、一个核心函数或单一配置对象时，应优先采用 export default。每个模块文件只能有一个默认导出：

// services/UserService.js
export default class UserService {
  constructor(apiEndpoint) {
    this.endpoint = apiEndpoint;
  }

  async fetchUser(id) {
    const res = await fetch(`${this.endpoint}/users/${id}`);
    return res.json();
  }
}

4. 模块聚合与转发导出（Re-exporting / Barrels）

在稍具规模的工程项目中，往往会将各类子模块按目录组织。为了避免外部调用方层层深入目录引用，通常在子目录根目录下建立 index.js，统一收集并对外聚合导出：

// utils/index.js
// 从子模块直接转发出所有命名导出
export * from './math.js';
export * from './format.js';

// 单独提取默认导出并重命名为具名导出
export { default as UserService } from '../services/UserService.js';

三、导入（import）实战：多维度按需加载

消费模块通过 import 关键字进行。由于ESM是静态解析的，常规的 import 语句必须出现在模块的最顶层作用域，不能嵌套在任何 if、for 或函数体内部。

1. 按需命名导入与别名处理

针对命名导出的模块，导入端使用花括号精准指定需要引入的变量或方法名，名称必须与导出端一致：

// main.js
import { add, PI } from './utils/math.js';
import { formatCurrency as toRMB } from './utils/format.js';

console.log(add(10, 20));          // 30
console.log(toRMB(128.5));         // ¥128.50

2. 默认导出的接收

导入默认导出时无需使用花括号，并且导入端可以完全自主决定本地引用的标识符名称：

// 导入端可自由命名为 UserService，也可命名为 UserClient
import UserService from './services/UserService.js';

const client = new UserService('https://api.example.com');

3. 命名空间整体导入

如果目标模块导出了较多内容，且希望将其归集在一个命名空间对象下统一调用，可以使用 * as 语法：

import * as MathTools from './utils/math.js';

console.log(MathTools.PI);
console.log(MathTools.add(5, 8));

4. 动态导入（Dynamic import()）

当需要根据运行时条件、路由变化或用户交互事件来延迟加载某些体积庞大的功能模块时，可以使用函数形式的 import(specifier)。它返回一个 Promise，支持在任何代码块与异步函数内部执行：

// 仅在用户点击导出报表按钮时，按需懒加载 Excel 导出组件
button.addEventListener('click', async () => {
  try {
    const { exportToExcel } = await import('./modules/excelExporter.js');
    exportToExcel(tableData);
  } catch (err) {
    console.error('模块懒加载失败:', err);
  }
});

图2：现代模块化工程组织架构、门面聚合模式与导入调用关系全景

四、实战演练：在浏览器与 Node.js 中运行 ES Module

虽然语法是一致的，但在具体落地运行模块化代码时，浏览器端与Node.js端在解析规则和配置方式上存在明显差异。下面以一个包含两个文件的最小实战工程演示完整的运行流程。

步骤 1：构建工程文件目录

在本地工作区创建如下目录结构：

esm-demo/
├── package.json      # Node.js 环境配置
├── math.js           # 工具模块
├── app.js            # 主程序入口
└── index.html        # 浏览器宿主页面

步骤 2：编写模块与入口逻辑

// math.js
export function multiply(x, y) {
  return x * y;
}

export const APP_NAME = 'ESM-Runner';

// app.js
// 注意：在原生ESM环境中，必须显式书写 .js 扩展名
import { multiply, APP_NAME } from './math.js';

const result = multiply(6, 7);
console.log(`[${APP_NAME}] 6 * 7 计算结果为:`, result);

if (typeof document !== 'undefined') {
  document.getElementById('output').textContent = `计算成功: 6 * 7 = ${result}`;
}

步骤 3：配置与执行（区分环境）

场景 A：在现代浏览器中运行

在HTML中引入JS脚本时，必须为 <script> 标签添加 type="module" 属性。浏览器一旦识别到该属性，就会以模块模式加载并执行脚本，同时默认具备 defer 异步延迟执行效果：

<!-- index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
  <meta charset="UTF-8">
  <title>ESM 浏览器运行测试</title>
</head>
<body>
  <h1>ES Module 浏览器实战</h1>
  <div id="output">正在加载模块...</div>

  <!-- 关键：声明 type="module" -->
  <script type="module" src="./app.js"></script>
</body>
</html>

场景 B：在 Node.js 环境中运行

Node.js 默认将 .js 文件视作 CommonJS 规范。要让 Node.js 原生将项目识别为 ES Module，推荐在项目的 package.json 中显式声明 "type": "module"：

{
  "name": "esm-demo",
  "version": "1.0.0",
  "type": "module"
}

配置完成后，直接使用命令行运行即可：

# 示例运行命令（无需安装任何转译工具）
node app.js

# 终端输出示例：
# [ESM-Runner] 6 * 7 计算结果为: 42

图3：ES Module 从代码规范编写到浏览器与 Node.js 双端执行的标准化操作链路

五、避坑指南：初学者高频报错与核心机理解析

在从传统的脚本写法或CommonJS迁移到ES Module时，由于运行机制和安全策略的改变，初学者常常会遇到以下典型问题：

1. 浏览器端 file:// 协议触发 CORS 跨域拦截报错

报错表现：在本地直接双击打开 index.html 时，浏览器控制台报错：Access to script at 'file:///.../app.js' from origin 'null' has been blocked by CORS policy。

原因分析：出于安全隔离设计，现代浏览器对声明了 type="module" 的资源采用同源检查策略，而本地的 file:// 协议的源被解析为 null，因而触发跨域拦截。

解决途径：必须通过轻量级本地 HTTP 服务器访问页面。例如可以在命令行使用 npx serve .、python3 -m http.server 8000 或使用 VS Code 的 Live Server 插件打开，通过 http://localhost:8000 进行调试。

2. 导入路径漏写 .js 扩展名（Node.js 原生报错）

报错表现：在 Node.js 中执行 import { add } from './math' 时，报错：Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...。

原因分析：在 CommonJS 中，Node.js 运行时会自动尝试补全 .js、.json、.node 后缀或查找 index.js。但在原生 ES Module 规范中，为了与浏览器加载行为保持完全一致，不支持自动后缀猜解与目录默认文件推导，必须提供包含扩展名的完整确切路径。

解决途径：显式补齐相对路径与后缀：import { add } from './math.js';。

3. 试图直接篡改导入的变量（实时只读绑定规则）

报错表现：对导入的命名导出直接赋值报错：TypeError: Assignment to constant variable。

原因分析：ES Module 导入的变量是“只读的动态实时映射（Live Read-Only Binding）”。你可以读取它的最新值，源模块内部的方法也可以修改它，但导入端没有权限对其重新赋值。

// counter.js
export let count = 0;
export function increment() { count++; }

// main.js
import { count, increment } from './counter.js';

// 错误做法：外部直接赋值（抛出 TypeError）
// count = 10; 

// 正确做法：调用源模块暴露的变更函数
increment();
console.log(count); // 此时 count 正确更新为 1

4. 找不到 __dirname 与 __filename 的替代方案

在 Node.js 的 CommonJS 模式中，每个文件都有内置的全局变量 __dirname（当前文件目录）和 __filename（当前文件绝对路径）。但在 ESM 中这两个变量不复存在。取而代之的是标准的 import.meta.url：

// 在 Node.js ESM 模块中获取当前文件所在目录的现代标准写法
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';

const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

console.log('当前目录路径:', __dirname);

六、ES Module 常用语法全景速查

为了帮助读者在日常开发中快速选用恰当的语法，下图对常用导入导出模式、对应语法形式与核心应用场景进行了系统归纳：

图4：ES Module 四类核心导出导入机制、语法样例与落地场景全景速查对照

七、总结

ES Module 不仅仅是 JavaScript 语言层面语法的升级，更是现代前端工程化生态的基石。理解其“静态分析期构建”与“实时只读绑定”的本质，有助于开发者在日常编码中写出依赖清晰、可维护性更高且天生利于打包压缩的代码。

在实际工程中，建议遵循以下最佳实践：

• 保持职责单一：工具库以命名导出为主，提高 Tree-shaking 消除冗余代码的效率；单一功能类与主入口组件使用默认导出。
• 合理利用目录聚合：使用 index.js 构建模块门面，简化调用方路径，降低目录层级重构时的重构成本。
• 规范文件扩展名与服务协议：在 Node.js ESM 环境下养成补全 .js 扩展名的习惯；在本地测试浏览器 ESM 模块时，务必使用本地 Web 服务器避免 CORS 阻断。