ES 模組

本指南旨在說明什麼是 ES 模組，以及如何使 Nuxt 應用程式（或上游函式庫）與 ESM 相容。

背景

CommonJS 模組

CommonJS (CJS) 是 Node.js 引入的一種格式，允許在隔離的 JavaScript 模組之間共享功能（深入了解）。您可能已經熟悉這種語法

const a = require('./a')

module.exports.a = a

像 webpack 和 Rollup 這樣的打包工具支援這種語法，並允許您在瀏覽器中使用以 CommonJS 撰寫的模組。

ESM 語法

大多數時候，當人們談論 ESM 與 CJS 時，他們指的是用於撰寫 模組 的不同語法。

import a from './a'

export { a }

在 ECMAScript 模組 (ESM) 成為標準之前（這花了十多年！），像 webpack 這樣的工具，甚至像 TypeScript 這樣的語言，都開始支援所謂的 ESM 語法。然而，與實際規範之間存在一些關鍵差異；這裡有 一個有用的解釋。

什麼是「原生」ESM？

您可能已經使用 ESM 語法撰寫應用程式很長一段時間了。畢竟，瀏覽器原生支援它，並且在 Nuxt 2 中，我們將您撰寫的所有程式碼編譯為適當的格式（伺服器的 CJS，瀏覽器的 ESM）。

當將模組添加到您的套件時，情況會有些不同。一個範例函式庫可能會同時公開 CJS 和 ESM 版本，並讓我們選擇我們想要的版本

{
  "name": "sample-library",
  "main": "dist/sample-library.cjs.js",
  "module": "dist/sample-library.esm.js"
}

因此，在 Nuxt 2 中，打包工具 (webpack) 會為伺服器建置提取 CJS 檔案 ('main')，並為客戶端建置使用 ESM 檔案 ('module')。

然而，在最近的 Node.js LTS 版本中，現在可以在 Node.js 中使用原生 ESM 模組。這表示 Node.js 本身可以使用 ESM 語法處理 JavaScript，儘管它預設不這樣做。啟用 ESM 語法最常見的兩種方式是

• 在您的 package.json 中設定 "type": "module"，並繼續使用 .js 副檔名
• 使用 .mjs 檔案副檔名（推薦）

這就是我們為 Nuxt Nitro 所做的事情；我們輸出一個 .output/server/index.mjs 檔案。這告訴 Node.js 將此檔案視為原生 ES 模組。

在 Node.js 環境中，哪些是有效的匯入？

當您 import 一個模組而不是 require 它時，Node.js 會以不同的方式解析它。例如，當您匯入 sample-library 時，Node.js 將尋找該函式庫的 package.json 中的 exports 或 module 條目，而不是 main。

動態匯入也是如此，例如 const b = await import('sample-library')。

Node 支援以下幾種匯入類型（請參閱 文件）

1. 以 .mjs 結尾的檔案 - 這些檔案預期使用 ESM 語法
2. 以 .cjs 結尾的檔案 - 這些檔案預期使用 CJS 語法
3. 檔名結尾為 .js 的檔案 - 預期會使用 CJS 語法，除非它們的 package.json 檔案中有 "type": "module" 設定

可能會有什麼問題？

長期以來，模組作者一直在產出 ESM 語法的建構版本，但使用像是 .esm.js 或 .es.js 這樣的慣例，並將其添加到他們 package.json 檔案中的 module 欄位。直到現在這都還不是問題，因為這些檔案一直以來都只被像 webpack 這樣的打包工具使用，而這些工具並不在意檔案副檔名。

然而，如果您嘗試在 Node.js ESM 環境中匯入帶有 .esm.js 檔案的套件，它將無法運作，並且您會收到類似以下的錯誤訊息

(node:22145) Warning: To load an ES module, set "type": "module" in the package.json or use the .mjs extension.
/path/to/index.js:1

export default {}
^^^^^^

SyntaxError: Unexpected token 'export'
    at wrapSafe (internal/modules/cjs/loader.js:1001:16)
    at Module._compile (internal/modules/cjs/loader.js:1049:27)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1114:10)
    ....
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

如果您從 Node.js 認為是 CJS 的 ESM 語法建構版本中進行具名匯入，您也可能會收到此錯誤

file:///path/to/index.mjs:5
import { named } from 'sample-library'
         ^^^^^
SyntaxError: Named export 'named' not found. The requested module 'sample-library' is a CommonJS module, which may not support all module.exports as named exports.

CommonJS modules can always be imported via the default export, for example using:

import pkg from 'sample-library';
const { named } = pkg;

    at ModuleJob._instantiate (internal/modules/esm/module_job.js:120:21)
    at async ModuleJob.run (internal/modules/esm/module_job.js:165:5)
    at async Loader.import (internal/modules/esm/loader.js:177:24)
    at async Object.loadESM (internal/process/esm_loader.js:68:5)

ESM 問題疑難排解

如果您遇到這些錯誤，問題幾乎可以肯定是出在上游函式庫。他們需要修正他們的函式庫，以支援被 Node.js 匯入。

轉譯函式庫

在此期間，您可以告知 Nuxt 不要嘗試匯入這些函式庫，方法是將它們添加到 build.transpile 中

export default 
defineNuxtConfig
({
  
build
: {
    
transpile
: ['sample-library']
  }
})

您可能會發現您也需要添加其他被這些函式庫匯入的套件。

別名函式庫

在某些情況下，您可能還需要手動將函式庫別名指向 CJS 版本，例如

export default 
defineNuxtConfig
({
  
alias
: {
    'sample-library': 'sample-library/dist/sample-library.cjs.js'
  }
})

預設匯出

具有 CommonJS 格式的依賴項，可以使用 module.exports 或 exports 來提供預設匯出

module.exports = { test: 123 }
// or
exports.test = 123

如果我們 require 這樣的依賴項，通常可以正常運作

const pkg = require('cjs-pkg')

console.log(pkg) // { test: 123 }

原生 ESM 模式下的 Node.js，啟用 esModuleInterop 的 typescript 以及像 webpack 這樣的打包工具，提供了一種相容性機制，使我們可以預設匯入這樣的函式庫。這種機制通常被稱為「互通 require 預設值」

import pkg from 'cjs-pkg'

console.log(pkg) // { test: 123 }

然而，由於語法檢測和不同捆綁格式的複雜性，總是存在互通預設值失敗的風險，最終我們可能會得到像這樣的結果

import pkg from 'cjs-pkg'

console.log(pkg) // { default: { test: 123 } }

此外，當使用動態匯入語法（在 CJS 和 ESM 檔案中）時，我們總是會遇到這種情況

import('cjs-pkg').then(console.log) // [Module: null prototype] { default: { test: '123' } }

在這種情況下，我們需要手動互通預設匯出

// Static import
import { default as pkg } from 'cjs-pkg'

// Dynamic import
import('cjs-pkg').then(m => m.default || m).then(console.log)

為了處理更複雜的情況和提高安全性，我們推薦並在 Nuxt 內部使用 mlly，它可以保留具名匯出。

import { interopDefault } from 'mlly'

// Assuming the shape is { default: { foo: 'bar' }, baz: 'qux' }
import myModule from 'my-module'

console.log(interopDefault(myModule)) // { foo: 'bar', baz: 'qux' }

函式庫作者指南

好消息是，修正 ESM 相容性問題相對簡單。主要有兩個選項

1. 您可以將您的 ESM 檔案重新命名為以 .mjs 結尾。
   這是推薦且最簡單的方法。 您可能需要解決函式庫依賴項以及可能與您的建構系統相關的問題，但在大多數情況下，這應該可以為您解決問題。為了最大的明確性，也建議您將 CJS 檔案重新命名為以 .cjs 結尾。
2. 您可以選擇使您的整個函式庫僅限 ESM.
   這意味著在您的 package.json 中設定 "type": "module"，並確保您建構的函式庫使用 ESM 語法。但是，您可能會遇到與您的依賴項相關的問題 - 而且這種方法意味著您的函式庫只能在 ESM 環境中使用。

遷移

從 CJS 到 ESM 的初始步驟是更新所有 require 的用法，改為使用 import

module.exports = ...

exports.hello = ...

const myLib = require('my-lib')

在 ESM 模組中，與 CJS 不同，require、require.resolve、__filename 和 __dirname 全域變數不可用，應替換為 import() 和 import.meta.filename。

import { join } from 'path'

const newDir = join(__dirname, 'new-dir')

const someFile = require.resolve('./lib/foo.js')

最佳實踐

• 偏好具名匯出而不是預設匯出。這有助於減少 CJS 衝突。（請參閱預設匯出章節）
• 盡可能避免依賴 Node.js 內建模組和 CommonJS 或僅限 Node.js 的依賴項，以使您的函式庫可在瀏覽器和 Edge Workers 中使用，而無需 Nitro polyfill。
• 使用帶有條件匯出的新 exports 欄位。（閱讀更多）。

{
  "exports": {
    ".": {
      "import": "./dist/mymodule.mjs"
    }
  }
}