import.meta 是 ES 模塊（ESM）特有的元數(shù)據(jù)對(duì)象，提供當(dāng)前模塊的上下文信息，是 ES 標(biāo)準(zhǔn)的一部分（ES2020 引入），Node.js 從 v12.2.0 開(kāi)始支持（需啟用 ESM，v14.13.0 及以上無(wú)需實(shí)驗(yàn)性標(biāo)志）。本文從核心概念、Node.js 專屬特性、使用場(chǎng)景、注意事項(xiàng)等維度全面解析。

一、基礎(chǔ)前提：?jiǎn)⒂?ES 模塊

Node.js 默認(rèn)使用 CommonJS 模塊，import.meta 僅在 ESM 中可用，需通過(guò)以下方式啟用 ESM：

1. 文件后綴為 .mjs；
2. package.json 中配置 "type": "module"；
3. 執(zhí)行時(shí)通過(guò) --input-type=module 運(yùn)行字符串代碼（如 node --input-type=module -e "console.log(import.meta)"）。

二、import.meta核心特性

1. 本質(zhì)：模塊級(jí)別的只讀對(duì)象

• import.meta 是每個(gè) ES 模塊獨(dú)有的實(shí)例，不同模塊的 import.meta 互不相同；
• 不可賦值（import.meta = {} 會(huì)報(bào)錯(cuò)），但對(duì)象內(nèi)部屬性可修改（如 import.meta.url = 'xxx' 僅影響當(dāng)前模塊的該屬性）；
• 僅在模塊頂層可用，不能在函數(shù)、類等作用域內(nèi)直接訪問(wèn)（需閉包捕獲）。

2. 標(biāo)準(zhǔn)屬性：import.meta.url（跨平臺(tái)通用）

import.meta.url 是 import.meta 最核心的屬性，返回當(dāng)前模塊的文件 URL 路徑（而非本地文件系統(tǒng)路徑），格式為 file:// 開(kāi)頭（本地文件）或 http:///https://（遠(yuǎn)程模塊）。

示例：基礎(chǔ)使用

// 假設(shè)文件路徑：/user/project/index.mjs
console.log(import.meta.url); 
// 輸出：file:///user/project/index.mjs（mac/Linux）
// 輸出：file:///C:/user/project/index.mjs（Windows，注意盤符大寫）

關(guān)鍵轉(zhuǎn)換：URL 轉(zhuǎn)本地文件路徑

Node.js 提供 node:url 模塊的 fileURLToPath 方法，可將 import.meta.url 轉(zhuǎn)為操作系統(tǒng)兼容的本地路徑：

import { fileURLToPath } from 'node:url';
import { dirname, join } from 'node:path';

// 當(dāng)前文件的本地路徑
const __filename = fileURLToPath(import.meta.url);
// 當(dāng)前文件所在目錄（替代 CommonJS 的 __dirname）
const __dirname = dirname(__filename);

console.log(__filename); // /user/project/index.mjs（mac/Linux）
console.log(__dirname); // /user/project
console.log(join(__dirname, 'utils', 'helper.mjs')); // 拼接路徑

三、Node.js 專屬擴(kuò)展屬性

Node.js 為 import.meta 擴(kuò)展了多個(gè)平臺(tái)特有的屬性，補(bǔ)充模塊運(yùn)行時(shí)的上下文信息：

1.import.meta.resolve（v18.19.0+/v20.0.0+ 穩(wěn)定）

異步方法，用于解析模塊路徑（類似 require.resolve，但適配 ESM），返回解析后的模塊 URL。

語(yǔ)法：

const resolvedUrl = await import.meta.resolve(specifier[, parentURL]);

• specifier：要解析的模塊路徑（相對(duì)/絕對(duì)/裸模塊）；
• parentURL：可選，解析的基準(zhǔn) URL（默認(rèn)是當(dāng)前模塊的 import.meta.url）。

示例：

// 解析相對(duì)模塊
const utilsUrl = await import.meta.resolve('./utils.mjs');
console.log(utilsUrl); // file:///user/project/utils.mjs

// 解析裸模塊（如 npm 包）
const lodashUrl = await import.meta.resolve('lodash');
console.log(lodashUrl); // file:///user/project/node_modules/lodash-es/lodash.mjs

// 自定義基準(zhǔn)路徑
const customUrl = await import.meta.resolve('helper.mjs', 'file:///user/project/lib/');

2.import.meta.dirname&import.meta.filename（v20.11.0+ 穩(wěn)定）

Node.js 提供的語(yǔ)法糖，直接替代手動(dòng)轉(zhuǎn)換的 __dirname/__filename，無(wú)需引入 url/path 模塊。

示例：

// /user/project/app.mjs
console.log(import.meta.filename); // /user/project/app.mjs（本地路徑，無(wú) file://）
console.log(import.meta.dirname);  // /user/project

3.import.meta.main（判斷模塊是否為入口）

返回布爾值：true 表示當(dāng)前模塊是 Node.js 進(jìn)程的入口文件，false 表示模塊被其他模塊導(dǎo)入。

示例：

// app.mjs
if (import.meta.main) {
  console.log('我是入口模塊');
  // 執(zhí)行入口邏輯
} else {
  console.log('我是被導(dǎo)入的模塊');
}

// 運(yùn)行 node app.mjs → 輸出「我是入口模塊」
// 其他模塊 import './app.mjs' → 輸出「我是被導(dǎo)入的模塊」

替代 CommonJS 的 require.main === module。

4.import.meta.resolveSync（同步版本，v18.19.0+/v20.0.0+ 穩(wěn)定）

import.meta.resolve 的同步版本，適用于無(wú)需異步的場(chǎng)景：

const path = import.meta.resolveSync('./config.mjs');
console.log(path);

5. 實(shí)驗(yàn)性屬性（謹(jǐn)慎使用）

• import.meta.url.slice(7)：手動(dòng)截取 file:// 前綴（不推薦，建議用 fileURLToPath）；
• import.meta.env：非 Node.js 原生屬性，通常由構(gòu)建工具（Vite、Webpack）注入環(huán)境變量，Node.js 原生不支持。

四、核心使用場(chǎng)景

1. 替代 CommonJS 的__dirname/__filename

ESM 中移除了 __dirname/__filename，需通過(guò) import.meta 實(shí)現(xiàn)相同功能：

// 兼容低版本 Node.js（v20.11.0 以下）
import { fileURLToPath } from 'node:url';
import { dirname } from 'node:path';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// v20.11.0+ 簡(jiǎn)化寫法
const { dirname, filename } = import.meta;

2. 動(dòng)態(tài)加載模塊

結(jié)合 import() 動(dòng)態(tài)導(dǎo)入，基于 import.meta.url 解析相對(duì)路徑：

// 動(dòng)態(tài)加載當(dāng)前目錄下的模塊
async function loadModule(moduleName) {
  const moduleUrl = new URL(`./${moduleName}.mjs`, import.meta.url).href;
  const module = await import(moduleUrl);
  return module;
}

loadModule('utils').then(utils => utils.doSomething());

3. 讀取模塊所在目錄的文件

結(jié)合 fs/promises 讀取本地文件，基于 import.meta.dirname 拼接路徑：

import { readFile } from 'node:fs/promises';

async function readConfig() {
  // v20.11.0+
  const configPath = `${import.meta.dirname}/config.json`;
  // 低版本替代：join(__dirname, 'config.json')
  const content = await readFile(configPath, 'utf8');
  return JSON.parse(content);
}

4. 多環(huán)境模塊入口判斷

通過(guò) import.meta.main 實(shí)現(xiàn)模塊的「復(fù)用+入口」雙模式：

// utils.mjs
export function add(a, b) {
  return a + b;
}

// 僅作為入口時(shí)執(zhí)行測(cè)試
if (import.meta.main) {
  console.log('測(cè)試 add 方法：', add(1, 2)); // 3
}

5. 解析第三方模塊的真實(shí)路徑

通過(guò) import.meta.resolve 查看 npm 包的實(shí)際安裝路徑：

async function getPackagePath(pkgName) {
  const url = await import.meta.resolve(pkgName);
  // 轉(zhuǎn)為本地路徑
  const path = fileURLToPath(url);
  console.log(`${pkgName} 的路徑：`, path);
}

getPackagePath('express'); // 輸出 express 入口文件的本地路徑

五、注意事項(xiàng)與坑點(diǎn)

1. 僅支持 ESM，CommonJS 不可用

如果在 .cjs 文件或未啟用 ESM 的 .js 文件中訪問(wèn) import.meta，會(huì)直接報(bào)錯(cuò) ReferenceError: import is not defined。

2.import.meta.url是 URL 而非本地路徑

• Windows 系統(tǒng)中，import.meta.url 格式為 file:///C:/xxx/xxx，直接拼接路徑會(huì)導(dǎo)致錯(cuò)誤，必須用 fileURLToPath 轉(zhuǎn)換；
• 遠(yuǎn)程模塊（如 import 'https://cdn.example.com/module.mjs'）的 import.meta.url 是遠(yuǎn)程 URL，無(wú)本地路徑。

3. 模塊頂層 await 不影響import.meta

即使模塊使用頂層 await，import.meta 仍可正常訪問(wèn)：

// 合法
const resolved = await import.meta.resolve('./a.mjs');
console.log(import.meta.url);

4.import.meta.main與子進(jìn)程/工作線程

• 子進(jìn)程（child_process）中執(zhí)行的模塊，import.meta.main 為 true（子進(jìn)程獨(dú)立入口）；
• 工作線程（worker_threads）中，import.meta.main 取決于線程入口是否為該模塊。

5. 兼容性問(wèn)題

六、與 CommonJS 等效對(duì)比

七、總結(jié)

import.meta 是 ESM 模塊的核心元數(shù)據(jù)工具，Node.js 基于標(biāo)準(zhǔn)擴(kuò)展了實(shí)用屬性，核心價(jià)值在于：

1. 替代 CommonJS 的 __dirname/__filename/require.resolve 等特性；
2. 提供模塊上下文信息（入口判斷、路徑解析）；
3. 適配 ESM 的模塊化規(guī)范，支持動(dòng)態(tài)路徑解析。

使用建議：

• 優(yōu)先使用穩(wěn)定屬性（如 url、main、dirname），避免實(shí)驗(yàn)性 API；
• 低版本 Node.js 需通過(guò) fileURLToPath 手動(dòng)轉(zhuǎn)換路徑；
• 結(jié)合 import() 動(dòng)態(tài)導(dǎo)入時(shí)，用 new URL(relativePath, import.meta.url) 解析路徑，避免相對(duì)路徑陷阱。

到此這篇關(guān)于深入理解Node.js中import.meta的使用的文章就介紹到這了,更多相關(guān)Node.js import.meta內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論