Node.js dan esbuild: berhati-hati dengan mencampurkan cjs dan esm

TL;DR

Apabila menggunakan esbuild untuk menggabungkan kod dengan --platform=node yang bergantung pada pakej npm dengan campuran titik masuk cjs dan esm, gunakan peraturan praktikal berikut:

• Apabila menggunakan --bundle, tetapkan --format kepada cjs. Ini akan berfungsi dalam semua kes kecuali untuk modul esm dengan menunggu peringkat teratas.
  • --format=esm boleh digunakan tetapi memerlukan polyfill seperti ini.
• Apabila menggunakan --packages=external, tetapkan --format kepada esm.

Jika anda tertanya-tanya tentang perbezaan antara cjs dan esm, lihat Node.js: Sejarah ringkas cjs, bundlers dan esm.

simptom

Apabila melaksanakan kod gabungan esbuild dengan --platform=node, anda mungkin terjumpa salah satu daripada ralat masa jalan berikut:

Error: Dynamic require of "<module_name>" is not supported

Error [ERR_REQUIRE_ESM]: require() of ES Module (...) from (...) not supported.
Instead change the require of (...) in (...) to a dynamic import() which is available in all CommonJS modules.

sebab

Ini adalah kerana salah satu daripada had berikut:

• transformasi esm kepada cjs (dan sebaliknya) esbuild.
• Saling kendali Node.js cjs/esm.

Analisis

esbuild mempunyai keupayaan transformasi terhad antara esm dan cjs. Selain itu, sesetengah senario semasa disokong oleh esbuild tidak disokong oleh Node.js sendiri. Mulai esbuild@0.24.0, jadual berikut meringkaskan perkara yang disokong:

Format	Scenario	Supported?
cjs	static import	Yes
cjs	dynamic import()	Yes
cjs	top-level await	No
cjs	--packages=external of esm entry point	No*
esm	require() of user modules**	Yes***
esm	require() of node:* modules	No****
esm	--packages=external of cjs entry point	Yes

* Disokong oleh esbuild tetapi bukan oleh Node.js

** Merujuk kepada pakej npm atau fail laluan relatif.

*** Modul pengguna disokong dengan beberapa kaveat: __dirname dan __filename tidak disokong tanpa polyfill.

**** nod:* modul boleh disokong dengan polyfill yang sama.

Yang berikut ialah penerangan terperinci senario ini tanpa menggunakan sebarang polifill:

---

pakej npm

Kami akan menggunakan contoh pakej npm berikut:

import statik

modul esm dengan import statik:

Error: Dynamic require of "<module_name>" is not supported

import dinamik

modul esm dengan import dinamik() dalam fungsi async:

Error [ERR_REQUIRE_ESM]: require() of ES Module (...) from (...) not supported.
Instead change the require of (...) in (...) to a dynamic import() which is available in all CommonJS modules.

peringkat atas-menunggu

modul esm dengan import dinamik() dan tahap tertinggi menanti:

import { version } from "node:process";

export function getVersion() {
  return version;
}

memerlukan

modul cjs dengan permintaan require():

export async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

---

--format=cjs

Kami akan menjalankan esbuild dengan hujah berikut:

const { version } = await import("node:process");

export function getVersion() {
  return version;
}

dan kod berikut:

const { version } = require("node:process");

exports.getVersion = function() {
  return version;
}

import statik

Menghasilkan yang berikut yang berfungsi dengan baik:

esbuild --bundle --format=cjs --platform=node --outfile=bundle.cjs src/main.js

import dinamik()

Menghasilkan yang berikut yang berfungsi dengan baik:

import { getVersion } from "{npm-package}";

(async () => {
  // version can be `string` or `Promise<string>`
  const version = await getVersion();

  console.log(version);
})();

Perhatikan bagaimana import() dinamik tidak ditukar kepada require() kerana ia juga dibenarkan dalam modul cjs.

peringkat atasan menanti

esbuild gagal dengan ralat berikut:

// node_modules/static-import/index.js
var import_node_process = require("node:process");
function getVersion() {
  return import_node_process.version;
}

// src/main.js
(async () => {
  const version2 = await getVersion();
  console.log(version2);
})();

--pakej=luaran

Menggunakan --packages=external berjaya dengan semua pakej npm:

// (...esbuild auto-generated helpers...)

// node_modules/dynamic-import/index.js
async function getVersion() {
  const { version } = await import("node:process");
  return version;
}

// src/main.js
(async () => {
  const version = await getVersion();
  console.log(version);
})();

menghasilkan:

[ERROR] Top-level await is currently not supported with the "cjs" output format

    node_modules/top-level-await/index.js:1:20:
      1 │ const { version } = await import("node:process");
        ╵                     ~~~~~

Walau bagaimanapun, kesemuanya gagal dijalankan kerana Nodes.js tidak membenarkan modul cjs mengimport modul esm:

esbuild --packages=external --format=cjs --platform=node --outfile=bundle.cjs src/main.js

---

--format=esm

Kini kami akan menjalankan esbuild dengan hujah berikut:

var npm_package_import = require("{npm-package}");
(async () => {
  const version = await (0, npm_package_import.getVersion)();
  console.log(version);
})();

memerlukan() modul pengguna

src/main.js

/(...)/bundle.cjs:1
var import_static_import = require("static-import");
                           ^

Error [ERR_REQUIRE_ESM]: require() of ES Module /(...)/node_modules/static-import/index.js from /(...)/bundle.cjs not supported.
Instead change the require of index.js in /(...)/bundle.cjs to a dynamic import() which is available in all CommonJS modules.

menghasilkan yang berikut yang berfungsi dengan baik:

esbuild --bundle --format=esm --platform=node --outfile=bundle.mjs src/main.js

memerlukan() modul nod:*

src/main.js

const { getVersion } = require("static-import");

console.log(getVersion());

menghasilkan yang berikut:

// (...esbuild auto-generated helpers...)

// node_modules/static-import/index.js
var static_import_exports = {};
__export(static_import_exports, {
  getVersion: () => getVersion
});
import { version } from "node:process";
function getVersion() {
  return version;
}
var init_static_import = __esm({
  "node_modules/static-import/index.js"() {
  }
});

// src/main.js
var { getVersion: getVersion2 } = (init_static_import(), __toCommonJS(static_import_exports));
console.log(getVersion2());

Walau bagaimanapun, ia gagal dijalankan:

import { getVersion } from "require";

console.log(getVersion());

--pakej=luaran

Menggunakan --packages=external berjaya dengan semua pakej npm, termasuk yang mempunyai titik masuk cjs. Contohnya:

// (...esbuild auto-generated helpers...)

var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
}) : x)(function(x) {
  if (typeof require !== "undefined") return require.apply(this, arguments);
  throw Error('Dynamic require of "' + x + '" is not supported');
});

// (...esbuild auto-generated helpers...)

// node_modules/require/index.js
var require_require = __commonJS({
  "node_modules/require/index.js"(exports) {
    var { version } = __require("node:process");
    exports.getVersion = function() {
      return version;
    };
  }
});

// src/main.js
var import_require = __toESM(require_require());
console.log((0, import_require.getVersion)());

dengan:

src/index.js

Error: Dynamic require of "node:process" is not supported

menghasilkan output hampir verbatim yang berjalan dengan baik kerana modul esm boleh mengimport pakej npm dengan titik masuk cjs:

esbuild --packages=external --format=esm --platform=node --outfile=bundle.mjs src/main.js

---

Kesimpulan

Saya harap anda mendapati siaran ini berguna untuk menyelesaikan masalah output esbuild sekarang dan pada masa hadapan. Beritahu saya pendapat anda di bawah!

Atas ialah kandungan terperinci Node.js dan esbuild: berhati-hati dengan mencampurkan cjs dan esm. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!