紀錄工作經驗、相關知識,解決技術相關問題。

Javascript, 新手 Jamp Holes

ES Modules 是什麼?JavaScript import/export 模組語法與 CommonJS 的差異

ES Modules 是什麼?JavaScript import/export 模組語法與 CommonJS 的差異 特色圖片

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 的說明列出的行為裡,最常碰到的有四個:

  1. 自動是 strict mode,而且只有模組可以使用 import 與 export。
  2. 有自己的作用域:沒有 export 的內容在模組外看不到。
  3. import 只能寫在最上層:import 宣告只能出現在模組的最上層,不能放在區塊或函式裡,宣告會被提升,匯入模組的副作用先於本模組其餘程式碼執行。要延後載入就用動態 import()。
  4. 匯入的是唯讀的 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:

Chrome 158 headless、Windows 11 以本機 HTTP 伺服器開啟 type="module" 頁面,畫面顯示 Hello, ES Modules
Chrome 158 headless、Windows 11:經本機 HTTP 伺服器載入的結果

模組 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.
Chrome 158 headless、Windows 11 以 file:// 開啟同一份頁面,畫面仍顯示尚未載入
Chrome 158 headless、Windows 11:以 file:// 開啟的結果

解法是用本機 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=moduleES 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 的差異

項目CommonJSES 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。依環境分兩種處理:

  1. 在瀏覽器:把 <script> 加上 type="module"。
<script type="module" src="./main.js"></script>
  1. 在 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()。有兩種處理:

  1. 把 require() 改成 import。
import fs from 'node:fs';
  1. 真的需要 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 與動態載入〉。

參考資料與延伸閱讀

發佈留言