[FEE-307] ES 模組與模組系統
INFO
JavaScript 在誕生後的前 20 年都沒有模組系統。腳本透過全域物件共享一切,社群發明了 CommonJS、AMD 和 UMD 來填補空缺。ES Modules(ESM)於 ES2015 標準化,終於為這門語言提供了原生、靜態、非同步的模組系統。因為 ESM 的 import/export 結構是靜態的,打包工具能夠移除未使用的匯出,瀏覽器也能在不透過打包工具的情況下載入模組。掌握 CJS 與 ESM 的分歧之處,才能避免混合式程式碼庫最終打包出同一個相依套件的兩個副本。
背景
在 ES2015 之前,JavaScript 沒有語言層級的模組系統。一個從單一 <script> 標籤開始、隨著時間有機成長的程式碼庫,通常會把所有函式都掛在一個全域命名空間物件上;當某個檔案需要另一個檔案定義的工具函式時,就得依賴 <script> 標籤的載入順序來決定當下有什麼可用。Node.js 於 2009 年採用了 CommonJS(CJS),為伺服器端程式碼提供 require() 和 module.exports。瀏覽器端則仰賴檔案串接、AMD(define/require)或 UMD 包裝。每種方式都有其取捨:
- CommonJS 同步且動態。它在 Node 中運作良好,因為模組是從本機檔案系統載入的,但未經打包無法直接在瀏覽器中使用。
- AMD(RequireJS) 非同步且對瀏覽器友善,但其回呼語法冗長,並發展出獨立於 CJS 的生態系。
- UMD 是偵測環境並同時支援 CJS 和 AMD 的包裝模式,需要複雜的樣板程式碼,也無法進行靜態分析。
ES2015 將 import/export 引入為語法:屬於語言文法的一部分,而非執行期 API。因為 import 和 export 是宣告式的,且僅出現在頂層,工具可以在建置時期分析模組依賴圖,無需實際執行程式碼。這正是打包工具得以消除未使用函式、偵測循環依賴,或將檔案隱式的全域依賴轉換為明確、可追溯依賴的原因。
如今,ESM 是瀏覽器和 Node.js 的共同標準。但 CJS 仍然運行在數以百萬計的套件中,遷移路徑也相當細膩。前端工程師必須理解兩套系統、它們的語意差異,以及建置工具如何橋接彼此。
視覺對比
以下圖表展示了一個模組依賴圖,其中靜態匯入形成可搖樹優化的連結,而動態 import() 呼叫建立程式碼分割點:
實線箭頭代表靜態匯入:打包工具可以對這些模組的未使用匯出進行搖樹優化。只有 debounce 從 utils.js 被匯入,因此 throttle 會在正式打包中被消除。虛線箭頭代表動態 import() 呼叫:每個呼叫建立一個按需載入的獨立區塊。打包工具偵測到 api-client.js 被多個延遲區塊匯入,會將其提取為共用區塊以避免重複。
範例
1. ESM 具名匯出和預設匯出與匯入
// math.js -- 具名匯出(函式庫推薦用法)
export const PI = 3.14159265;
export function area(radius) {
return PI * radius ** 2;
}
export function circumference(radius) {
return 2 * PI * radius;
}
// logger.js -- 預設匯出(單一用途模組)
export default class Logger {
constructor(prefix) {
this.prefix = prefix;
}
log(msg) {
console.log(`[${this.prefix}] ${msg}`);
}
}
// app.js -- 匯入兩種風格
import Logger from "./logger.js"; // 預設匯入
import { area, circumference } from "./math.js"; // 具名匯入
// import * as math from "./math.js"; // 命名空間匯入(math.area、math.PI)
const logger = new Logger("App");
logger.log(`Circle area: ${area(5)}`);
logger.log(`Circumference: ${circumference(5)}`);
// 重新匯出模式(桶檔案 barrel file:index.js)
export { area, circumference } from "./math.js"; // 具名重新匯出
export { default as Logger } from "./logger.js"; // 將預設重新匯出為具名2. 動態 import() 延遲載入
// 路由層級程式碼分割
const routes = {
"/dashboard": () => import("./pages/Dashboard.js"),
"/settings": () => import("./pages/Settings.js"),
"/admin": () => import("./pages/AdminPanel.js"),
};
async function navigate(path) {
const loader = routes[path];
if (!loader) {
throw new Error(`Unknown route: ${path}`);
}
// import() 回傳一個解析為模組命名空間的 Promise
const module = await loader();
// 存取預設匯出(頁面元件)
const PageComponent = module.default;
// 或解構具名匯出
// const { PageComponent, pageTitle } = await loader();
renderPage(PageComponent);
}
// 基於功能旗標的載入
async function loadAnalytics() {
if (window.__FEATURE_FLAGS__.analytics) {
const { init, trackEvent } = await import("./analytics.js");
init({ siteId: "abc123" });
return trackEvent;
}
return () => {}; // 停用時回傳空操作
}3. Import map 實現無打包工具的 CDN 解析
<!DOCTYPE html>
<html>
<head>
<!-- Import map:將裸指定符(bare specifiers)解析至 CDN URL -->
<script type="importmap">
{
"imports": {
"lodash-es": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/lodash.js",
"lodash-es/": "https://cdn.jsdelivr.net/npm/lodash-es@4.17.21/",
"preact": "https://esm.sh/preact@10.19.3",
"preact/": "https://esm.sh/preact@10.19.3/",
"htm": "https://esm.sh/htm@3.1.1"
}
}
</script>
</head>
<body>
<!-- type="module" 在瀏覽器中啟用 ESM -->
<script type="module">
// 裸指定符現在透過 import map 解析 -- 不需要打包工具
import { debounce } from "lodash-es";
import { h, render } from "preact";
import htm from "htm";
const html = htm.bind(h);
function App() {
return html`<h1>Hello from ESM + Import Maps</h1>`;
}
render(html`<${App} />`, document.body);
</script>
</body>
</html>4. 使用 import.meta.url 解析模組相對路徑
// data-loader.js -- 解析「此模組自身」的相對路徑,
// 而非目前工作目錄或頁面 URL 的相對路徑
const dataUrl = new URL("./fixtures/countries.json", import.meta.url);
// 瀏覽器:fetch() 可以直接接受這個 URL。
export async function loadCountries() {
const response = await fetch(dataUrl);
return response.json();
}
// Node.js:import.meta.url 是 file:// URL,而 Node 的全域 fetch()
// (undici)不接受 file: 協定,改為讀取檔案 --
// fs/promises 可以直接接受 file:// URL:
// import { readFile } from "node:fs/promises";
// export async function loadCountries() {
// const text = await readFile(dataUrl, "utf8");
// return JSON.parse(text);
// }
// import.meta.url 是目前模組的絕對 URL(瀏覽器)或 file:// URL
// (Node.js)。因為它是逐模組解析的,函式庫可以定位自己打包的
// 資源,無論使用端專案從何處匯入它 -- 只要存取方式(fetch 或
// fs)與執行環境相符即可。5. JSON 模組的 import attributes
// config.json
// { "apiVersion": 3, "features": ["search", "export"] }
// app.js -- import attributes 取代了已淘汰的 "assert" 語法
import config from "./config.json" with { type: "json" };
console.log(config.apiVersion); // 3
// 動態 import() 也接受相同的 attribute:
const { default: locale } = await import(`./locales/${lang}.json`, {
with: { type: "json" },
});Import attributes(with { type: "json" })是 ES2025 的一部分,用來告訴模組載入器該如何解讀一個非 JavaScript 的資源。它取代了此提案還在 Stage 3 階段時使用的 assert { type: "json" } 語法;現在瀏覽器和 Node.js 都只接受 with 形式。JSON 模組匯入在 Node.js 22+ 以及目前版本的 Chrome、Edge、Firefox 和 Safari 中皆可直接使用,無需旗標。另一個相關提案 import defer(TC39 Stage 3)讓模組能夠完整載入,但將其頂層程式碼的執行延後,直到其中一個匯出真正被讀取為止:import defer * as ns from "./heavy-plugin.js";。它無法延後一個自身使用頂層 await 的模組,因為存取延後命名空間的屬性必須保持同步;當一個延後模組的依賴圖中僅有其依賴項目使用了頂層 await 時,這些非同步模組會被提前求值,而依賴圖中同步的部分則仍延後至首次存取時才求值。
最佳實踐
優先使用具名匯出而非預設匯出以利搖樹優化。 應(SHOULD)在函式庫和共用工具程式碼中使用具名匯出,因為打包工具能識別並消除個別未使用的匯出。預設匯出只暴露單一個不透明的 binding。若該 binding 是含有多個成員的物件或類別,打包工具便無法靜態確定哪些成員被使用,因而必須納入整個值。應避免(AVOID)在同一個模組中混用預設匯出和具名匯出,因為這會為使用者製造不一致的匯入語法,也會使重構更加困難。
避免模組間的循環依賴。 應(SHOULD)在建構模組時確保不存在匯入循環。在 ES modules 中,匯入的 binding 是指向匯出 slot 的即時參照。若模組 A 從 B 匯入、B 從 A 匯入,且 A 是進入點,則 B 會先被求值;B 的頂層程式碼會在 A 自己的頂層程式碼執行之前讀取 A 的匯出值,因而產生 ReferenceError。若循環無法消除,應將存取移至兩個模組皆完整求值後才呼叫的函式中。
使用 import.meta.url 處理模組相對路徑。 應(SHOULD)在模組需要解析相對於自身、而非相對於目前工作目錄的檔案路徑或 URL 時,使用 import.meta.url。import.meta 物件僅在模組腳本內可用,提供目前模組的規範 URL,使資源參照無論從何處載入模組都能可靠地解析。
使用動態 import() 進行程式碼分割。 應(SHOULD)在路由邊界、功能旗標後方,以及重型可選相依套件處使用 import(),而非在啟動時載入所有內容。import() 回傳一個解析為模組命名空間物件的 Promise;打包工具將每個 import() 呼叫視為分割點,並產生按需載入的獨立 chunk。應優先在 import() 內使用靜態字串指定符,讓打包工具能在建置時期確定分割點集合。
設計思維
為何 ESM 採用靜態結構設計
ESM 的根本設計選擇,是模組依賴圖能夠在靜態階段,也就是解析時期、不執行任何程式碼的情況下,被完整確定。這是首要的設計目標,並非偶然的副作用。
在 CommonJS 中,require() 是一個函式呼叫。它可以出現在條件式、迴圈或函式內部,引數可以是計算出的字串。這意味著沒有任何工具能在不執行程式碼的情況下得知完整的依賴圖:
// CJS:動態 -- 工具無法靜態分析
const mod = require(condition ? "./a" : "./b");
const name = getModuleName();
const dynamic = require(`./plugins/${name}`);ESM 的 import MUST 是頂層宣告,且模組指定符(specifier)必須為字串字面值:
// ESM:靜態 -- 工具可在解析時期分析
import { debounce } from "lodash-es";
import { render } from "./render.js";此限制解鎖了三項改變 JavaScript 工具生態的能力:
搖樹優化(Tree-shaking,死碼消除)。 Rollup 率先實現此技術:若
import { debounce } from "lodash-es"是唯一的匯入,打包工具能證明 lodash-es 的所有其他匯出皆未使用,從而將它們排除在打包結果之外。使用 CJS 時,因為require()回傳的是整個module.exports物件,必須包含整個模組。建置時期依賴分析。 打包工具在產生輸出前建構完整的模組依賴圖。這使得作用域提升(scope hoisting,將模組合併為更少的函式)、程式碼分割(識別共用區塊)和平行載入策略成為可能。
快速刷新與 HMR(Hot Module Replacement)。 開發伺服器可以精確判斷哪些模組依賴於被修改的檔案,僅更新那些模組,而無需重新執行整個依賴樹。
深入探討
打包工具如何利用靜態結構
Rollup 專為 ESM 而建。其搖樹優化分析整個打包範圍中哪些繫結(bindings)被實際使用,不僅移除未使用的匯出,還移除模組內未使用的內部函式。Rollup 的輸出通常最小,因為它從一開始就是為 ESM 設計的。
webpack 在 v2 透過「harmony modules」分析加入了搖樹優化支援。webpack 4 引入了 sideEffects 欄位:當套件宣告 "sideEffects": false 時,webpack 可以在沒有任何匯出被匯入的情況下跳過整個模組。webpack 5 改進了逐匯出使用追蹤和巢狀搖樹優化。
Vite 在開發階段採取不同策略:將原始檔案作為原生 ESM 透過 HTTP 提供,完全不進行打包。瀏覽器自身的模組載入器按需取得每個檔案,使開發伺服器的啟動速度幾乎不受應用程式大小影響。Vite 在提供檔案之前仍會預打包(pre-bundle)相依套件,原因有二:
- CJS/UMD 轉換。 像 React 這樣以 CJS 發布的相依套件,Vite 將其轉換為 ESM 以便瀏覽器載入。
- 模組數量縮減。 某些 ESM 套件包含數百個內部模組(lodash-es 有 600 多個)。預打包將它們合併為單一檔案,避免瀑布式(waterfall)HTTP 請求。
Vite 使用 Rolldown 進行預打包,這是一個採用 Oxc 剖析器的 Rust 打包工具,現在接手了先前由 esbuild 擔任的角色。自 Vite 8(於 2026 年 3 月成為穩定版)起,Rolldown 也成為預設的正式環境打包工具,取代 Rollup,將開發與正式環境的建置流程統一在同一套引擎之下。
框架的程式碼分割與動態 import()
動態 import() 回傳一個 Promise,解析為模組的命名空間物件。打包工具將 import() 視為分割點,為匯入的模組及其依賴建立獨立區塊(chunk)。
React 使用 React.lazy() 包裝動態匯入以進行元件層級分割:
const Dashboard = React.lazy(() => import("./Dashboard"));
function App() {
return (
<Suspense fallback={<Spinner />}>
<Dashboard />
</Suspense>
);
}Vue 的 defineAsyncComponent() 提供相同模式:
const Dashboard = defineAsyncComponent(() => import("./Dashboard.vue"));SvelteKit 和 Next.js 更進一步採用路由層級的程式碼分割。每個頁面元件自動成為分割點:框架的路由器僅載入當前路由所需的程式碼。
Next.js 還提供 next/dynamic 進行元件層級分割,並自動按頁面分割,因此每個路由僅載入自己的 JavaScript。
遷移指南
將程式碼庫或套件從 CJS 遷移至 ESM,重點大多在於處理兩套系統之間如何互通,而非重寫邏輯。
雙重套件風險(Dual package hazard)。 若套件同時提供 CJS 和 ESM 進入點,專案可能同時載入兩個版本:CJS 透過 require()、ESM 透過 import,造成兩個狀態分歧的獨立實例。Node.js 文件特別警告此問題。
條件匯出(Conditional exports)(package.json 的 "exports" 欄位)透過讓你為不同環境指定不同進入點來處理雙重套件風險:
{
"name": "my-lib",
"type": "module",
"exports": {
".": {
"module-sync": "./dist/index.mjs",
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
}
}
}"type": "module" 在 package.json 中告訴 Node.js 將套件內所有 .js 檔案視為 ESM。若未設定,.js 檔案預設為 CJS。你可以使用 .mjs 代表 ESM、.cjs 代表 CJS 來逐檔覆寫,不受 type 欄位影響。
Node.js 現在可以 require() 同步的 ESM。 require(esm) 自 Node.js 20.19 和 22.12 起已不需旗標即可使用,並在後續版本中被正式標記為穩定功能。CommonJS 檔案可以 require() 一個 ES module 並取得其命名空間物件,前提是該模組的依賴圖中不含頂層 await;若含有頂層 await 則會拋出 ERR_REQUIRE_ASYNC_MODULE。這本身並不能完全消除雙重套件風險,但它移除了最常見的觸發情境:CJS 使用端需要一個僅提供 ESM 的相依套件時,不再需要動態 import() 的權宜解法。這正是上方 exports map 中 "module-sync" 條件的用途:在支援它的 Node.js 版本上,module-sync 會讓 import 和 require() 都解析到同步的 ESM 檔案,並覆蓋排在其後的 require 條件。"require": "./dist/index.cjs" 這一項僅作為 fallback,供 require(esm) 出現前(< 20.19 / 22.12)的 Node.js 版本使用。在現代 Node 上,require() 已不再需要解析到一份手動維護的 CJS 版本。
常見失效模式
1. 循環依賴與暫時性死區(TDZ)
// a.js(進入點)
import { b } from "./b.js";
console.log("a.js 頂層程式碼,b =", b);
export const a = "A";
// b.js
import { a } from "./a.js";
console.log("b.js 頂層程式碼,a =", a);
export const b = "B";
// 以 a.js 作為進入點載入時,會先求值其依賴項 b.js。
// b.js 的頂層程式碼嘗試讀取 `a`,但 a.js 尚未執行到
// `export const a = "A"` -- 它仍在等待 b.js 執行完畢。此時該
// binding 已存在,但仍處於暫時性死區(TDZ)中,因此會拋出:
// ReferenceError: Cannot access 'a' before initialization
// 整個依賴圖的求值到此中止;a.js 自己的 console.log 那一行,
// 以及 b.js 的 `export const b = "B"`,都不會執行。
//
// CJS 處理同樣的循環方式不同:require() 回傳呼叫當下
// module.exports 所持有的內容,那可能是一個不完整
// (partial)的物件,而不是拋出例外。
//
// 修正:重構以消除循環,或將讀取移至兩個模組都
// 完整求值後才執行的函式中。
export function getA() {
return a; // 安全:在模組求值完成「之後」才被呼叫,而非求值期間
}2. 動態 import() 使用樣板字面值導致靜態分析失效
// 不佳:打包工具無法在建置時期判斷可能的值
async function loadPlugin(name) {
const plugin = await import(`./plugins/${name}.js`);
return plugin.default;
}
// 打包工具必須:
// - 包含 ./plugins/ 下的所有檔案(過度打包),或
// - 放棄優化,僅保留為執行期匯入(無法最佳化)
// 較佳:使用靜態對應,讓打包工具知道確切的集合
const pluginLoaders = {
chart: () => import("./plugins/chart.js"),
table: () => import("./plugins/table.js"),
calendar: () => import("./plugins/calendar.js"),
};
async function loadPlugin(name) {
const loader = pluginLoaders[name];
if (!loader) throw new Error(`Unknown plugin: ${name}`);
const plugin = await loader();
return plugin.default;
}3. 頂層 await 造成瀑布式載入
// slow.js -- 頂層 await 阻塞所有依賴此模組的模組
const config = await fetch("/api/config").then(r => r.json());
const translations = await fetch(`/api/i18n/${config.locale}`).then(r => r.json());
export { config, translations };
// 這兩個 fetch 依序執行(瀑布式),且每一個匯入 slow.js 的模組
// 都必須等待兩個 fetch 完成後才能開始求值。
// 修正:改為匯出 Promise 或初始化函式
let _config;
let _translations;
export async function init() {
_config = await fetch("/api/config").then(r => r.json());
_translations = await fetch(`/api/i18n/${_config.locale}`).then(r => r.json());
}
export function getConfig() { return _config; }
export function getTranslations() { return _translations; }
// app.js -- 呼叫端控制非同步工作的時機
import { init, getConfig } from "./slow.js";
await init(); // 明確且可見,由擁有時序控制的模組負責4. 假設搖樹優化能移除所有未使用的程式碼(sideEffects 欄位)
// 函式庫的 package.json -- 缺少 sideEffects 宣告
{
"name": "my-ui-lib",
"main": "dist/index.cjs",
"module": "dist/index.mjs"
// 沒有 "sideEffects" 欄位!
}
// 函式庫的 index.mjs:
import "./polyfills.js"; // 副作用:修改全域物件
import "./register-components.js"; // 副作用:註冊自訂元素
export { Button } from "./Button.js";
export { Modal } from "./Modal.js";
export { Tabs } from "./Tabs.js";
// 使用者僅匯入 Button:
import { Button } from "my-ui-lib";
// 缺少 "sideEffects" 欄位時,打包工具 MUST 包含 polyfills.js
// 和 register-components.js,因為它們可能有副作用。
// 即使未使用的匯出如 Modal 和 Tabs 也可能被保留。
// 修正:在 package.json 中宣告 sideEffects
{
"name": "my-ui-lib",
"sideEffects": [
"./dist/polyfills.js",
"./dist/register-components.js",
"**/*.css"
]
}
// 現在打包工具知道:只有列出的檔案具有副作用。
// 其他所有檔案都可以安全地進行搖樹優化。延伸閱讀
- FEE-300 -- JavaScript 核心與執行環境概覽:模組運作所依賴的執行模型
- FEE-301 -- 事件迴圈與工作佇列:動態
import()是非同步的,與微任務佇列(microtask queue)整合 - FEE-302 -- 閉包與作用域:模組作用域即閉包,每個模組擁有自己的頂層作用域
- FEE-800 -- 建置工具:打包工具(Rollup、webpack、Vite)仰賴 ESM 的靜態結構進行最佳化
參考資料
- ECMA-262 -- Scripts and Modules -- 定義 Source Text Module Records、import/export 語法和模組求值語意的規範
- MDN -- JavaScript modules guide -- ESM 語法、動態匯入和瀏覽器使用的完整指南
- MDN -- import statement -- 靜態匯入宣告的語法與語意
- MDN -- export statement -- 具名匯出、預設匯出和重新匯出
- MDN -- Import attributes -- ES2025 的
with { type: "json" }語法,用於 JSON 和 CSS 模組匯入,以及它從assert遷移而來的歷史 - MDN -- import map -- 使用
<script type="importmap">在瀏覽器中解析裸指定符 - Node.js -- ECMAScript modules -- Node.js ESM 支援、與 CJS 的互通性(包含
require(esm)與module-sync條件)、條件匯出和"type": "module" - Node.js -- CommonJS modules --
require()系統、模組解析演算法和快取行為 - Lin Clark -- ES modules: A cartoon deep-dive -- 以插畫說明模組建構、實例化和求值三大階段
- Vite -- Dependency Pre-Bundling -- Vite 如何將 CJS 轉換為 ESM 並合併內部模組以提升開發效能
- Vite -- Why Vite -- 原生 ESM 開發伺服器架構及其解決的問題
- webpack -- Tree Shaking guide --
sideEffects欄位、逐匯出分析和死碼消除 - V8 -- Dynamic import() -- 動態模組載入的執行期語意
- TC39 --
import deferproposal -- 關於延後模組求值直到命名空間屬性首次被存取的 Stage 3 提案