JavaScript · ES Modules 与工程化

场景 1 · 首屏瘦身: 路由级 dynamic import 分包

单页应用 2.8MB 首包, 图表/编辑器/大表格全在里面。按路由拆 chunk, 首屏只下真正用到的:

// 路由表: 组件改懒加载
const routes = {
  '/dashboard': () => import('./pages/dashboard.js'),
  '/editor':    () => import('./pages/editor.js'),    // monaco 只在这进包
};
async function navigate(path) {
  loading.start();
  const { render } = await routes[path]();   // 按需下载+执行
  render(container);
  loading.end();
}

首包 2.8MB → 760KB, FCP 从 4.1s 降到 1.6s。

场景 2 · 库的摇树落地: sideEffects 与发布审计

工具库 1.2MB, 用户只 import 一个函数却全量进包。三步收敛:

// 1. package.json 声明无副作用(有副作用的文件列出)
{ "sideEffects": false }
// 2. 源码: 用命名导出, 别 export default 大对象
export function deepClone(o) { ... }
// 3. 审计产物: 构建后确认产物只含被引用函数
// rollup.config: treeshake: { moduleSideEffects: false }

用户侧体积 1.2MB → 18KB; 附带产物: 库自身的冷启动也变快。

场景 3 · 双格式发布: ESM + CJS 双轨不翻车

库要同时服务 bundler(ESM)与老 Node(CJS), 关键是 exports 条件映射 + 防双实例:

{ "name": "mylib",
  "type": "module",
  "exports": {
    ".": {
      "types": "./types/index.d.ts",
      "import": "./esm/index.js",     // bundler/现代 node
      "require": "./cjs/index.cjs"     // 老 node/测试框架
    } } }
// 关键: 状态(单例)库要防"esm 与 cjs 各一份实例"
// → 全局唯一状态走 globalThis 注册或仅提供无状态 API

场景 4 · 循环依赖重构: 把共享下沉

order 与 invoice 互相引用, 测试偶发 undefined is not a function。下沉共享类型与工具, 断开环:

// 前: order.js ↔ invoice.js 互相 import
// 后:
// shared/types.js   ← 两个方向都只依赖它
// order.js → shared/types.js ← invoice.js
// 无法完全断开时: 延迟到函数体内 import() 或参数注入
invoiceFor(order) { const { build } = await import('./invoice.js'); }

场景 5 · 懒初始化单例: 顶层 await 替代 init() 仪式

老模式 await init(); const db = getDb(); 每个入口都要写。改成初始化即模块:

// db.js (ESM)
export const pool = await createPool();    // 顶层 await
export async function query(sql, p) { return pool.query(sql, p); }
// 业务模块: import { query } from './db.js' 直接用
// 关键: 连接就绪前, 依赖 db 的模块根本不会执行

场景 6 · 环境注入: import.meta.env 而非 process.env

前端代码里残留 process.env 在浏览器直接崩。统一走打包器注入的 import.meta.env:

// vite/现代 bundler
const api = import.meta.env.VITE_API_BASE;
// 类型安全: src/env.d.ts 里声明
// interface ImportMetaEnv { readonly VITE_API_BASE: string }
// CI 注入: VITE_API_BASE=https://api.prod build

场景 7 · 深导入治理: exports 锁住包的公共面

用户偷偷 import 内部文件, 内部重构全线爆炸。exports 白名单挡住深导入:

{ "exports": {
    ".": "./index.js",
    "./utils/*": null } }        // 显式禁止 utils 深导入
// 或仅开放 ./components/*:
// "./components/*": "./src/components/*.js"
// 未列路径: import 'lib/internal/x.js' → ERR_PACKAGE_PATH_NOT_EXPORTED

场景 8 · 关键路由预加载: modulepreload

登录页懒加载 dashboard, 跳转时白屏 800ms。空闲时预取目标 chunk:

// 登录成功后, 空闲预取下一跳
requestIdleCallback(() => {
  const l = document.createElement('link');
  l.rel = 'modulepreload';
  l.href = '/assets/dashboard-abc123.js';   // 构建产物真实文件名
  document.head.append(l);
});
// 或 import(/* webpackPrefetch: true */ ...) 由构建器生成

场景 9 · 依赖审计: 找出没人用的导出与依赖

三年老仓库 40% 依赖已无人引用。用静态分析工具清库:

npx knip                # 未用导出/依赖/文件 + 循环依赖报告
npx depcheck            # 未用依赖专项
npx madge --circular src   # 循环依赖专项
# 治理顺序: 先删未用依赖 → 断循环(下沉共享) → 收敛未用导出

node_modules 体积 -38%, 循环依赖 12 条 → 0。

场景 10 · Worker 里的 ESM: type: 'module'

Worker 里想复用业务模块, 老式经典 worker 只能 importScripts 拼。现代写法直接支持 ESM:

const w = new Worker('/workers/render.js', { type: 'module' });
// render.js 内部可以正常 import 共享模块:
// import { geometry } from '../shared/geometry.js';
// Node 侧: new Worker('./render.js') 直接支持 ESM