JavaScript模块化开发import/export使用实例详解

JavaScript自ECMAScript 2015（ES6）起正式推出了官方模块规范（简称ESM，ECMAScript Modules）。在ESM诞生前，前端社区依赖全局变量、立即执行函数（IIFE）或AMD、CommonJS等第三方规范来组织代码，存在全局变量污染和依赖关系不明确等痛点。现代JavaScript通过export将函数、类、对象或原始值暴露给外界，再由import将其引入到另一个作用域中。本文将结合具体的代码案例，逐一梳理ESM的语法细节、环境适配方式、运行机制以及核心注意事项。

图1：ES Modules 静态解析与执行三阶段生命周期模型

一、运行环境与基础配置

ES模块在浏览器与Node.js中均得到原生支持，但由于执行宿主与历史兼容性原因，两者在识别ESM文件时有明确的配置要求。如果配置不当，会直接引发语法错误（如 SyntaxError: Cannot use import statement outside a module）。

图2：浏览器与 Node.js 启用 ES 模块的操作流程与环境要点

1. 浏览器环境启用

在HTML中加载JavaScript模块文件时，必须为 <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>

2. Node.js 环境启用

Node.js 历史默认使用 CommonJS 规范（require / module.exports）。如果需要在 Node.js 中直接运行原生的 import 和 export，推荐在项目根目录的 package.json 中添加字段：

{
  "name": "esm-demo",
  "version": "1.0.0",
  "type": "module",
  "scripts": {
    "start": "node src/main.js"
  }
}

配置完成后，Node.js 会将该目录下的所有 .js 文件均视为 ES 模块进行解析。若只想局部使用，可以将文件后缀命名为 .mjs，无需改动 package.json。

二、具名导出与导入（Named Export / Import）

具名导出允许一个模块导出多个变量、函数或类。每一个导出项在导出时都具有确定的名称，导入方通过精确的花括号解构语法按需提取。

1. 声明时直接导出

在变量、常量、函数或类声明的最前面直接加上 export 关键字：

// src/mathUtils.js
// 导出常量
export const PI = 3.14159265359;

// 导出具名函数
export function add(a, b) {
  return a + b;
}

// 导出类
export class Calculator {
  multiply(a, b) {
    return a * b;
  }
}

2. 集中统一导出

先在模块内正常声明，最后通过对象字面量结构的形式集中暴露。这是在大型工具模块中极为推荐的做法，清晰罗列了所有外露接口：

// src/formatUtils.js
function formatDate(timestamp) {
  const d = new Date(timestamp);
  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
}

function truncateString(str, maxLength = 20) {
  if (str.length <= maxLength) return str;
  return str.slice(0, maxLength) + '...';
}

// 集中具名导出
export { formatDate, truncateString };

3. 具名导入与重命名（as 关键字）

使用具名导入时，花括号 { ... } 中的名称必须与导出端完全一致。如果当前作用域中存在同名变量产生冲突，可以使用 as 关键字进行重命名：

// src/main.js
import { add, PI, Calculator } from './mathUtils.js';
import { formatDate, truncateString as shorten } from './formatUtils.js';

console.log(add(10, 20));          // 输出：30
console.log(PI);                    // 输出：3.14159265359

const calc = new Calculator();
console.log(calc.multiply(4, 5));   // 输出：20

console.log(formatDate(Date.now()));// 输出当前日期，例如 2026-10-24
console.log(shorten('JavaScript模块化深度解析指南', 8)); // 输出：JavaScript...

三、默认导出与导入（Default Export / Import）

默认导出适用于“一个模块主要完成一件事情”的场景，例如导出单个类、核心配置对象或主函数。每个模块文件只能存在一个 export default。

1. 默认导出的声明

// src/Logger.js
export default class Logger {
  constructor(prefix = 'APP') {
    this.prefix = prefix;
  }

  info(message) {
    console.log(`[${this.prefix}] [INFO]: ${message}`);
  }

  error(message) {
    console.error(`[${this.prefix}] [ERROR]: ${message}`);
  }
}

2. 默认导入的特点

导入默认导出时，不需要使用花括号，并且导入方可以自由指定接收名称，无需与导出文件的类名或变量名相同：

// src/app.js
// 自定义接收名称为 CustomLogger，无需花括号
import CustomLogger from './Logger.js';

const logger = new CustomLogger('USER-SERVICE');
logger.info('用户登录成功'); // 输出：[USER-SERVICE] [INFO]: 用户登录成功

3. 默认导出与具名导出混合使用

ESM 允许在同一个文件中同时存在一个 export default 和多个具名 export：

// src/apiClient.js
export const API_TIMEOUT = 5000;
export const BASE_URL = 'https://api.example.com/v1';

export default async function request(endpoint, options = {}) {
  const url = `${BASE_URL}${endpoint}`;
  console.log(`发起请求: ${url}，超时设定: ${API_TIMEOUT}ms`);
  // 模拟请求
  return { status: 200, data: { success: true } };
}

导入时，可以在一条 import 语句中同时接收默认项与具名项，默认项必须放在花括号之前：

// src/userService.js
// request 是默认导出，BASE_URL、API_TIMEOUT 是具名导出
import request, { BASE_URL, API_TIMEOUT } from './apiClient.js';

async function fetchUserList() {
  console.log(`目标服务地址: ${BASE_URL}`);
  return await request('/users');
}

图3：JavaScript 常见 import / export 语法与适用场景矩阵

四、聚合重导出（Re-export）与命名空间导入

在组织复杂项目架构或编写SDK库时，通常存在一个 index.js 作为向外公布的统一门面（Facade）。聚合重导出允许在不将模块内容载入当前作用域的前提下，直接转手暴露给第三方。

1. 命名空间导入（Namespace Import）

当一个模块导出了大量具名接口，且调用方需要组织化访问时，可以使用 * as Alias 将所有导出收集进一个对象容器：

// src/main.js
import * as MathService from './mathUtils.js';

// 通过命名空间对象进行访问
console.log(MathService.PI);
console.log(MathService.add(5, 10));

2. 聚合转手导出（Re-exporting）

在公共入口文件 index.js 中，可以使用 export ... from ... 语法：

// src/components/Button.js
export const Button = () => '<button>Click</button>';

// src/components/Modal.js
export const Modal = () => '<div class="modal">Modal</div>';

// src/components/index.js（统一聚合入口）
export { Button } from './Button.js';
export { Modal } from './Modal.js';

// 重导出并重命名
export { default as LoggerService } from '../Logger.js';

// 重导出全部具名导出
export * as Tools from '../formatUtils.js';

这样，外部使用者只需引入 index.js，而无需关注内部各个碎片的物理存储路径：

// 外部使用方
import { Button, Modal, LoggerService } from './components/index.js';

五、动态导入 import() 与按需加载

普通的 import ... from '...' 是静态语句，必须处于模块顶层，不能包裹在 if 分支、循环或普通函数体内部。如果希望在用户触发某个交互（如点击导出PDF按钮）时才加载重型依赖，可以使用基于 Promise 的函数式动态导入 import()。

1. 基础语法与 Promise 链式调用

// src/analyticsLoader.js
function trackEvent(eventName) {
  // 仅在被调用时动态加载统计 SDK
  import('./analyticsSdk.js')
    .then((module) => {
      module.sendData(eventName);
    })
    .catch((error) => {
      console.error('统计模块加载失败:', error);
    });
}

2. 结合 async / await 语法

// src/dashboard.js
const exportBtn = document.getElementById('export-pdf-btn');

exportBtn.addEventListener('click', async () => {
  try {
    exportBtn.disabled = true;
    exportBtn.innerText = '正在加载组件...';

    // 动态按需加载重型依赖模块
    const { generatePDF } = await import('./pdfGenerator.js');
    
    // 执行生成逻辑
    await generatePDF({ title: '月度财务报表', content: '数据明细...' });
    exportBtn.innerText = '导出完成';
  } catch (err) {
    console.error('动态导出功能异常:', err);
    exportBtn.innerText = '导出重试';
  } finally {
    exportBtn.disabled = false;
  }
});

六、ES模块运行机制与关键易错点

理解 ESM 与 CommonJS 的本质差异，是避免在真实工程中踩坑的关键。

1. 导出的是“动态引用绑定”（Live Bindings）而非值拷贝

在 CommonJS 中，require() 返回的是导出值的拷贝。而在 ESM 中，import 获得的是对导出模块内部变量的只读实时引用。当源模块内部修改了变量，导入方感知到的值会同步更新；但导入方不能直接赋值修改它。

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

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

console.log(count); // 输出：0
increment();
console.log(count); // 输出：1（源模块更新，导入方同步变更）

// 错误尝试：外部直接修改导入的绑定变量
// count = 10; // 抛出 TypeError: Assignment to constant variable.

2. 静态解析与单例缓存（Singleton）

同一个模块文件无论被多次 import 引入多少次，它的顶级作用域代码都只会执行一次。JavaScript 引擎会将解析好的模块记录缓存在 Module Map 中。后续引入均直接复用已初始化的内存引用，天然具备单例特性。

图4：ESM 模式选型决策路径与高频避坑排查速查表

七、总结

JavaScript官方的 import 与 export 模块系统为现代前端工程化提供了坚实的基础规范：

• 具名导出（Named Export）：适合多接口暴露与细粒度工具函数，支持打包工具精准的 Tree-Shaking 剔除无用代码。
• 默认导出（Default Export）：适用于单一核心职责模块（如组件、实体类），导入方可自由命名。
• 聚合导出（Re-export）：常用于包的顶级门面（如 index.js），封装内部文件结构。
• 动态导入（Dynamic Import）：通过 import() 实现按需异步加载，是前端性能优化与路由分包的核心手段。
• 运行原理：ESM 经过构建（Parse）、实例化（Instantiate）与求值（Evaluate）三个阶段，具备静态分析、实时只读引用绑定与单例缓存等关键特性。

在日常开发中，建议统一规范文件路径显式带上 .js 扩展名，合理拆分模块边界，即可写出高内聚、易测试且结构清晰的现代 JavaScript 程序。