ES Modules调优核心在于理解静态结构对加载、依赖和运行时的影响，而非仅语法正确；需明确模块边界、规避循环依赖风险、合理使用动态导入，并通过工具链协同验证模块行为。
ES Modules 的经典案例复盘与调优，核心不在“写对语法”，而在理解静态结构如何影响加载顺序、依赖图谱和运行时行为。真正卡住项目的，往往是看似正确的 import 写法背后隐藏的路径歧义、循环依赖暴露时机、动态导入误用，或构建工具对 ESM 特性的误判。
明确模块边界：从文件粒度到导出契约
一个常见误区是把“拆成多个 .js 文件”等同于“完成了模块化”。ESM 的边界由 export 和 import 显式定义，不是靠目录或命名自动形成。
- 每个文件只导出它对外承诺的接口，比如组件类、配置常量、纯函数，不导出内部工具、临时变量或未封装的 DOM 操作逻辑
- 禁用
import * as X from './X.js'，强制使用具名导入（import { render, config } from './X.js'）或默认导入（import X from './X.js'），避免隐藏依赖、阻碍 tree-shaking - 组件库或工具包根目录设
index.js作为唯一入口，只做有限 re-export；禁止子模块跨层直连（如Card.js直接 import../../utils/debounce.js），统一走shared/或lib/中转
处理循环依赖：看清 ESM 的“安全延迟”机制
CommonJS 遇到循环依赖会返回空对象，而 ESM 在解析阶段就建立模块记录（Module Record），执行时按声明顺序逐个求值——这使得循环依赖在 ESM 中可预测、可调试，但前提是理解“导出绑定”而非“值拷贝”。
- 若 A 导入 B，B 又导入 A，A 中的
export let count = 0在 B 中读取时拿到的是实时绑定，不是快照值 - 避免在顶层直接调用对方模块的函数（如
B.doSomething()），改用函数内调用或事件触发，把执行时机推迟到双方都已初始化完成 - 用 ESLint 插件
import/no-cycle提前发现潜在循环，比线上报undefined更早干预
动态导入不是“补救措施”，而是性能杠杆
import() 是函数调用，返回 Promise，它的价值不是“让 import 写在 if 里”，而是实现按需加载、代码分割和错误隔离。
- 首屏无关功能（如编辑器插件、报表导出、帮助弹窗）必须用
import('./editor.js').then(m => m.init())，不能写在顶层 - 配合
webpackChunkName或 Vite 的/* @vite-ignore */注释，让打包产物有可读 chunk 名，便于监控和缓存 - 动态导入后不要直接解构默认导出：
const { default: Component } = await import('./Modal.js')，应保持const mod = await import('./Modal.js'); mod.default.render()，避免破坏 ESM 的导出绑定语义
构建与运行时协同验证模块行为
ESM 本身不阻止非法访问，边界意识要靠工具链落地。
- 启用
import/no-unused-modules和no-unused-vars，自动清理未使用的导出，减少包体积 - 在 Vite 或 Webpack 中开启
build.rollupOptions.treeshake并设为true，确保未引用的命名导出被剔除 - Node.js 环境下测试 ESM 行为时，确认
type: "module"已写入package.json，且所有.js文件按 ESM 解析；避免混用require和import导致Cannot use import statement outside a module
