Node.js 및 esbuild: cjs와 esm 혼합에 주의하세요.

TL;DR

esbuild를 사용하여 cjs 및 esm 진입점이 혼합된 npm 패키지에 의존하는 --platform=node로 코드를 번들링하는 경우 다음 경험 법칙을 사용하세요.

• --bundle을 사용하는 경우 --format을 cjs로 설정하세요. 이는 최상위 대기 기능이 있는 esm 모듈을 제외한 모든 경우에 작동합니다.
  • --format=esm을 사용할 수 있지만 이와 같은 폴리필이 필요합니다.
• --packages=external을 사용하는 경우 --format을 esm으로 설정하세요.

cjs와 esm의 차이점이 궁금하다면 Node.js: cjs, 번들러, esm의 간략한 역사를 살펴보세요.

징후

--platform=node를 사용하여 esbuild 번들 코드를 실행할 때 다음 런타임 오류 중 하나가 발생할 수 있습니다.

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.

원인

다음 제한 사항 중 하나로 인해 발생합니다.

• esbuild의 esm을 cjs로(또는 그 반대로) 변환합니다.
• Node.js cjs/esm 상호 운용성.

분석

esbuild는 esm과 cjs 간의 변환 기능이 제한되어 있습니다. 또한 esbuild에서 지원되는 일부 시나리오는 Node.js 자체에서는 지원되지 않습니다. esbuild@0.24.0 기준으로 다음 표에 지원되는 내용이 요약되어 있습니다.

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

* esbuild에서는 지원되지만 Node.js에서는 지원되지 않습니다

** npm 패키지 또는 상대 경로 파일을 나타냅니다.

*** 사용자 모듈은 몇 가지 주의 사항과 함께 지원됩니다. __dirname 및 __filename은 폴리필 없이는 지원되지 않습니다.

**** node:* 모듈은 동일한 폴리필로 지원될 수 있습니다.

다음은 폴리필을 사용하지 않은 이러한 시나리오에 대한 자세한 설명입니다.

---

npm 패키지

다음 예제 npm 패키지를 사용합니다.

정적 가져오기

정적 임포트가 있는 esm 모듈:

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

동적 가져오기

비동기 함수 내에 동적 import()가 있는 esm 모듈:

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.

최상위 대기

동적 import() 및 최상위 수준 wait가 있는 esm 모듈:

import { version } from "node:process";

export function getVersion() {
  return version;
}

필요하다

require() 호출이 있는 cjs 모듈:

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

---

--format=cjs

다음 인수를 사용하여 esbuild를 실행합니다.

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

export function getVersion() {
  return version;
}

그리고 다음 코드:

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

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

정적 가져오기

잘 실행되는 다음을 생성합니다.

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

동적 가져오기()

잘 실행되는 다음을 생성합니다.

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

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

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

동적 import()가 cjs 모듈에서도 허용되기 때문에 require()로 변환되지 않는다는 점에 유의하세요.

최상위 수준 대기

다음 오류로 인해 esbuild가 실패합니다.

// 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);
})();

--패키지=외부

모든 npm 패키지에서 --packages=external을 사용하면 성공합니다.

// (...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);
})();

생산품:

[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");
        ╵                     ~~~~~

그러나 Nodes.js는 cjs 모듈이 esm 모듈을 가져오는 것을 허용하지 않기 때문에 모두 실행되지 않습니다.

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

---

--format=esm

이제 다음 인수를 사용하여 esbuild를 실행합니다.

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

사용자 모듈의 require()

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.

잘 실행되는 다음을 생성합니다.

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

node:* 모듈의 require()

src/main.js

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

console.log(getVersion());

다음을 생성합니다.

// (...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());

그러나 실행에 실패합니다:

import { getVersion } from "require";

console.log(getVersion());

--패키지=외부

cjs 진입점이 있는 패키지를 포함하여 모든 npm 패키지에서 --packages=external을 사용하면 성공합니다. 예:

// (...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)());

함께:

src/index.js

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

esm 모듈이 cjs 진입점을 사용하여 npm 패키지를 가져올 수 있기 때문에 거의 그대로 실행되는 출력을 생성합니다.

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

---

결론

이 게시물이 현재와 미래의 esbuild 출력 문제를 해결하는 데 도움이 되기를 바랍니다. 아래에서 여러분의 생각을 알려주세요!

위 내용은 Node.js 및 esbuild: cjs와 esm 혼합에 주의하세요.의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!