ES Modules 是什麼? ES Modules(簡稱 ESM)是 ECMAScript 標準的模組格式:每個檔案是一個模組,用 export 對外提供值,用 import 取用別的模組。Node.js 原本的模組格式是 CommonJS(require() 與 module.exports),ESM 則是瀏覽器與 Node.js 都支援的標準寫法。本文說明 import/export 語法、瀏覽器與 Node.js 怎麼啟用,以及和 CommonJS 的差異與常見錯誤。
ES Modules 是什麼:用 import 與 export 拆檔案
ECMAScript 規格的 Introduction 寫明,第 6 版(2015)的主要新增包含模組。Node.js 官方文件稱 ECMAScript modules 是「official standard format to package JavaScript code for reuse」,並提供與原本 CommonJS 格式的互通。ECMAScript 與 JavaScript 的關係、ES6 與年度版本怎麼對應,可前往〈ECMAScript 是什麼?和 JavaScript 的關係、ES6 與年度版本怎麼看〉。
先看最小的例子。math.mjs 用 export 提供三個東西:兩個具名匯出和一個預設匯出。
// math.mjs
export const PI2 = Math.PI * 2;
export function add(a, b) {
return a + b;
}
export default function multiply(a, b) {
return a * b;
}
main.mjs 用 import 取用:
// main.mjs
import multiply, { add, PI2 } from './math.mjs';
import * as math from './math.mjs';
console.log(add(2, 3));
console.log(multiply(2, 3));
console.log(PI2.toFixed(2));
console.log(Object.keys(math));
在 Node.js v22.20.0 執行 node main.mjs,輸出如下:
5
6
6.28
[ 'PI2', 'add', 'default' ]
具名匯出與預設匯出
MDN 說明,預設匯出沒有名稱,每個模組最多只能有一個預設匯出,具名匯出和預設匯出可以放在同一個模組。兩者在 import 時的寫法不同:
| 匯出寫法 | 匯入寫法 | 說明 |
|---|---|---|
export const PI2 = ... | import { PI2 } from './math.mjs' | 具名匯出,要用大括號且名稱一致 |
export default function ... | import multiply from './math.mjs' | 預設匯出,不加大括號,匯入端可自訂名稱 |
| 兩者並存 | import multiply, { add } from './math.mjs' | 預設匯入寫在前面 |
| 不限 | import * as math from './math.mjs' | math 是 namespace 物件,內含所有匯出 |
| 不限 | import './math.mjs' | 只執行模組、不匯入任何值 |
import * as math 的結果裡,預設匯出會變成名為 default 的屬性,所以上面的輸出有 'default'。
ES Modules 的幾個特性
MDN 的說明列出的行為裡,最常碰到的有四個:
- 自動是 strict mode,而且只有模組可以使用
import與export。 - 有自己的作用域:沒有
export的內容在模組外看不到。 import只能寫在最上層:import宣告只能出現在模組的最上層,不能放在區塊或函式裡,宣告會被提升,匯入模組的副作用先於本模組其餘程式碼執行。要延後載入就用動態import()。- 匯入的是唯讀的 live binding:匯出的模組可以改值,匯入端會看到新值,但匯入端不能重新指派。
第四點用計數器看得出來,inc() 在 counter.mjs 改了 count,匯入端讀到的值跟著變:
// counter.mjs
export let count = 0;
export function inc() {
count++;
}
// live.mjs
import { count, inc } from './counter.mjs';
console.log(count);
inc();
console.log(count);
0
1
在匯入端寫 count = 5; 則會得到 TypeError: Assignment to constant variable.。
瀏覽器怎麼用:script type="module"
瀏覽器要把檔案當模組載入,在 <script> 標籤加上 type="module"。MDN 的說明是,這個值會讓程式碼被當成 JavaScript 模組處理,內容的處理會延後(deferred)。三個檔案如下:
<!-- index.html -->
<!doctype html>
<html lang="zh-Hant">
<head>
<meta charset="utf-8">
<title>ES Modules 示範</title>
</head>
<body>
<div id="out">尚未載入</div>
<script type="module" src="./main.js"></script>
</body>
</html>
// greet.js
export function greet(name) {
return `Hello, ${name}`;
}
// main.js
import { greet } from './greet.js';
document.getElementById('out').textContent = greet('ES Modules');
用本機 HTTP 伺服器開啟 index.html,#out 的文字會從「尚未載入」變成 Hello, ES Modules:

模組 script 的載入行為
MDN 的 Modules on the web 說明了和傳統 script 不同的幾點:
- 自動 defer:沒有
async的模組 script 會自動 deferred,不需要再寫defer屬性;加上async後則載入完就立刻執行,不保證順序。 - 需要 JavaScript MIME type:伺服器要用含 JavaScript MIME type(例如
text/javascript)的Content-Type回應,否則瀏覽器報 MIME type 錯誤、不執行。副檔名在瀏覽器裡無關緊要,靠Content-Type與type="module"辨識。 - 要寫完整路徑:HTML 規格預設只接受相對於目前模組網址的 URL,不能省略副檔名或
index.js。 - 不能直接寫套件名稱:像
import { greet } from 'greet'這種 bare specifier,瀏覽器要靠 import map(<script type="importmap">裡的 JSON 物件)才能解析,不會去搜尋node_modules。 - 舊瀏覽器備援:
nomodule屬性讓支援 ES Modules 的瀏覽器略過該 script,可作舊瀏覽器的備援。
不能用 file:// 直接開啟
MDN 寫明,把網頁改成模組後,就不能再用 file:// 協定直接開啟 HTML;原因是模組請求使用 CORS,而 file:// 網址永遠不同源。同一份 index.html 用 file:// 開啟,頁面文字停在「尚未載入」,Console 的錯誤原文是:
Access to script at 'file:///…/main.js' from origin 'null' has been blocked by CORS policy:
Cross origin requests are only supported for protocol schemes: chrome, chrome-experimental-site-token-provider, chrome-extension, chrome-untrusted, data, http, https, isolated-app.

解法是用本機 HTTP 伺服器提供檔案。CORS 錯誤的一般成因與開發時的處理可前往〈如何使用Chrome套件解決Localhost開發中的CORS問題〉。
Node.js 怎麼用:.mjs 與 package.json 的 type
Node.js 要知道一個 .js 檔該用哪種模組格式解讀。官方文件列出的明確標記:
| 標記 | 解讀成 |
|---|---|
.mjs 副檔名 | ES module |
package.json 的 "type": "module" | 該套件內的 .js 檔是 ES module |
--input-type=module | ES module(用於直接給程式碼的情境) |
.cjs 副檔名 | CommonJS |
package.json 的 "type": "commonjs" | 該套件內的 .js 檔是 CommonJS |
官方文件寫明,沒有 "type" 欄位時,.js 檔視為 CommonJS。
沒有標記時:語法偵測
官方文件另外說明,程式碼沒有任何明確標記時,Node.js 會檢查原始碼有沒有 ES module 語法;有就當 ES module 執行,否則當 CommonJS。在 Node.js v22.20.0,沒有 package.json 的資料夾裡,內含 import 的 plain-import.js 可以直接執行。
官方文件提醒,在這種「語意不明」的檔案裡寫 ES module 語法有效能成本,建議明確標記。想讓專案統一用 ESM,在 package.json 加一行:
{
"type": "module"
}
設定後 .js 檔都以 ES module 執行;要保留某個檔案用 CommonJS,副檔名改成 .cjs。
相對路徑一定要寫副檔名
官方文件寫明,用 import 解析相對或絕對路徑時必須提供副檔名,目錄的 index 也要完整指定,這和瀏覽器裡 import 的行為一致。./math 少了副檔名會直接報錯:
// missing-ext.mjs
import { add } from './math';
console.log(add(1, 2));
Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'C:\demo\math' imported from C:\demo\missing-ext.mjs
改成 './math.mjs' 就正常。
ES Modules 與 CommonJS 的差異
| 項目 | CommonJS | ES Modules |
|---|---|---|
| 匯出 | module.exports = ... 或 exports.name = ... | export、export default |
| 匯入 | const x = require('...') | import x from '...'(只能在最上層) |
| 標準 | Node.js 原有的模組格式 | ECMAScript 標準,Node.js 與瀏覽器都支援 |
__filename、__dirname | 有 | 沒有,改用 import.meta.filename、import.meta.dirname |
require、module、exports | 有 | 沒有 |
Node.js 文件說明,CommonJS 的 exports 是 module.exports 的捷徑,但對 exports 重新指派新值後就不再綁定 module.exports;模組第一次載入後會被快取,多次 require('foo') 得到同一個物件。
ES Modules 裡沒有的變數
CommonJS 檔案裡直接可用的 require、module、exports、__filename、__dirname,在 ES module 裡都不存在。檢查結果如下:
// esm-noreq.mjs
console.log(typeof require);
console.log(typeof __dirname);
console.log(import.meta.dirname.endsWith('demo'));
console.log(import.meta.filename.endsWith('esm-noreq.mjs'));
console.log(import.meta.url.startsWith('file:///'));
undefined
undefined
true
true
true
在 ES module 呼叫 require() 會得到:
ReferenceError: require is not defined in ES module scope, you can use import instead
Node.js 文件的替代方案:路徑用 import.meta.filename 與 import.meta.dirname(只存在於 file: 協定的模組);真的需要 require 函式時,用 module.createRequire() 建立。
兩種格式互相載入
ES module 匯入 CommonJS
文件寫明,匯入 CommonJS 時,module.exports 物件會成為預設匯出,具名匯出是 Node.js 用靜態分析盡量提供的功能,不保證偵測得到,偵測不到時建議改用預設匯入:
// cjs-lib.cjs
exports.greet = function greet(name) {
return 'Hello, ' + name;
};
exports.version = '1.0.0';
// esm-import-cjs.mjs
import lib, { greet } from './cjs-lib.cjs';
console.log(greet('ESM'));
console.log(lib);
Hello, ESM
{ greet: [Function: greet], version: '1.0.0' }
CommonJS 載入 ES module
import 陳述式不能寫在 CommonJS 檔案裡,但官方文件指出動態 import() 運算式在 CommonJS 也能用來載入 ES module(用法見下一節)。
另一條路是 require() 直接載入 ES module。Node.js 文件說明,require() 只支援載入「完全同步」的 ES module,也就是沒有頂層 await 的模組;載入後回傳 module namespace 物件,預設匯出放在 .default 屬性。在 Node.js v22.20.0:
// cjs-require-esm.cjs
const math = require('./math.mjs');
console.log(math.add(1, 2));
console.log(typeof math.default, math.default(3, 4));
console.log(Object.keys(math));
3
function 12
[ 'PI2', '__esModule', 'add', 'default' ]
Object.keys 多了 __esModule:文件說明,有預設匯出時 namespace 會帶 __esModule: true,供既有的轉換工具辨識,屬於實驗性質,直接用 CommonJS 寫的程式碼應避免依賴它。
被 require() 的模組含有頂層 await 時,文件寫明會丟 ERR_REQUIRE_ASYNC_MODULE,要改用 import()。對含 await Promise.resolve('loaded') 的 tla.mjs 執行 require,用 try/catch 印出 e.code:
ERR_REQUIRE_ASYNC_MODULE
動態 import() 與頂層 await
靜態 import 只能放在最上層,要依條件或延後載入,用動態 import()。MDN 說明,import() 以模組路徑為參數,回傳 Promise,fulfilled 的值是 module namespace 物件。MDN 與 Node.js 文件也都寫明,await 可以直接寫在模組最上層,不必包在 async 函式裡:
// dynamic.mjs
const { add } = await import('./math.mjs');
console.log(add(1, 2));
執行 node dynamic.mjs 輸出 3。
常見錯誤訊息與處理
Q1:出現 SyntaxError: Cannot use import statement outside a module 怎麼辦?
MDN 說明,在非模組環境(例如沒有 type="module" 的 <script>)遇到 import 宣告會丟 SyntaxError。依環境分兩種處理:
- 在瀏覽器:把
<script>加上type="module"。
<script type="module" src="./main.js"></script>
- 在 Node.js:確認最近的
package.json沒有設成"type": "commonjs",把"type"改成"module",或把檔名改成.mjs。
{
"type": "module"
}
Q2:出現 ReferenceError: require is not defined in ES module scope 怎麼辦?
這代表檔案是 ES module(.mjs 或 package.json 設了 "type": "module"),但寫了 require()。有兩種處理:
- 把
require()改成import。
import fs from 'node:fs';
- 真的需要
require函式時,用module.createRequire()建立。
import { createRequire } from 'node:module';
const require = createRequire(import.meta.url);
const fs = require('node:fs');
打包工具與 ES Modules
Vite 的專案結構可前往〈React 工具鏈規格解析:基於 Vite 的初始化流程、目錄架構與生產環境建構〉;import 與 export 放在最上層,打包工具才能在建置時移除未用到的匯出,Tree Shaking 可前往〈JavaScript Code Splitting 與 Tree Shaking:減少首屏體積的拆分策略〉;瀏覽器載入 HTML 檔案的做法可前往〈HTML Modules 與 HTML Imports 演進:Import Attributes、宣告式 Shadow DOM 與動態載入〉。
參考資料與延伸閱讀
- Node.js:ECMAScript modules
- Node.js:Modules: CommonJS modules
- Node.js:Modules: Packages
- MDN:JavaScript modules
- MDN:Modules on the web
- MDN:import
- MDN:script 元素
- ECMAScript® 2027 Language Specification(最新草稿,tc39.es)
- 站內延伸閱讀:〈ECMAScript 是什麼?和 JavaScript 的關係、ES6 與年度版本怎麼看〉、〈如何使用Chrome套件解決Localhost開發中的CORS問題〉
發佈留言