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

一、基礎前提：啟用 ES 模塊

Node.js 默認使用 CommonJS 模塊，import.meta 僅在 ESM 中可用，需通過以下方式啟用 ESM：

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

二、import.meta核心特性

1. 本質：模塊級別的只讀對象

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

2. 標準屬性：import.meta.url（跨平臺通用）

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

示例：基礎使用

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

關鍵轉換：URL 轉本地文件路徑

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

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

// 當前文件的本地路徑
const __filename = fileURLToPath(import.meta.url);
// 當前文件所在目錄（替代 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 專屬擴展屬性

Node.js 為 import.meta 擴展了多個平臺特有的屬性，補充模塊運行時的上下文信息：

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

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

語法：

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

• specifier：要解析的模塊路徑（相對/絕對/裸模塊）；
• parentURL：可選，解析的基準 URL（默認是當前模塊的 import.meta.url）。

示例：

// 解析相對模塊
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

// 自定義基準路徑
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 提供的語法糖，直接替代手動轉換的 __dirname/__filename，無需引入 url/path 模塊。

示例：

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

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

返回布爾值：true 表示當前模塊是 Node.js 進程的入口文件，false 表示模塊被其他模塊導入。

示例：

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

// 運行 node app.mjs → 輸出「我是入口模塊」
// 其他模塊 import './app.mjs' → 輸出「我是被導入的模塊」

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

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

import.meta.resolve 的同步版本，適用于無需異步的場景：

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

5. 實驗性屬性（謹慎使用）

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

四、核心使用場景

1. 替代 CommonJS 的__dirname/__filename

ESM 中移除了 __dirname/__filename，需通過 import.meta 實現(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+ 簡化寫法
const { dirname, filename } = import.meta;

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

結合 import() 動態(tài)導入，基于 import.meta.url 解析相對路徑：

// 動態(tài)加載當前目錄下的模塊
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. 讀取模塊所在目錄的文件

結合 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)境模塊入口判斷

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

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

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

5. 解析第三方模塊的真實路徑

通過 import.meta.resolve 查看 npm 包的實際安裝路徑：

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

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

五、注意事項與坑點

1. 僅支持 ESM，CommonJS 不可用

如果在 .cjs 文件或未啟用 ESM 的 .js 文件中訪問 import.meta，會直接報錯 ReferenceError: import is not defined。

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

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

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

即使模塊使用頂層 await，import.meta 仍可正常訪問：

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

4.import.meta.main與子進程/工作線程

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

5. 兼容性問題

六、與 CommonJS 等效對比

七、總結

import.meta 是 ESM 模塊的核心元數(shù)據(jù)工具，Node.js 基于標準擴展了實用屬性，核心價值在于：

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

使用建議：

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

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

最新評論