Node.js `import.meta` 深入全面讲解

import.meta是 ES 模块（ESM）特有的元数据对象，提供当前模块的上下文信息，是 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. 执行时通过--input-type=module运行字符串代码（如node --input-type=module -e "console.log(import.meta)"）。

二、import.meta核心特性

1. 本质：模块级别的只读对象

• import.meta是每个 ES 模块独有的实例，不同模块的import.meta互不相同；
• 不可赋值（import.meta = {}会报错），但对象内部属性可修改（如import.meta.url = 'xxx'仅影响当前模块的该属性）；
• 仅在模块顶层可用，不能在函数、类等作用域内直接访问（需闭包捕获）。

2. 标准属性：import.meta.url（跨平台通用）

import.meta.url是import.meta最核心的属性，返回当前模块的文件 URL 路径（而非本地文件系统路径），格式为file://开头（本地文件）或http:///https://（远程模块）。

示例：基础使用

// 假设文件路径：/user/project/index.mjsconsole.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转为操作系统兼容的本地路径：

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/projectconsole.log(join(__dirname,'utils','helper.mjs'));// 拼接路径

三、Node.js 专属扩展属性

Node.js 为import.meta扩展了多个平台特有的属性，补充模块运行时的上下文信息：

1.import.meta.resolve（v18.19.0+/v20.0.0+ 稳定）

异步方法，用于解析模块路径（类似require.resolve，但适配 ESM），返回解析后的模块 URL。

语法：

constresolvedUrl=awaitimport.meta.resolve(specifier[,parentURL]);

• specifier：要解析的模块路径（相对/绝对/裸模块）；
• parentURL：可选，解析的基准 URL（默认是当前模块的import.meta.url）。

示例：

// 解析相对模块constutilsUrl=awaitimport.meta.resolve('./utils.mjs');console.log(utilsUrl);// file:///user/project/utils.mjs// 解析裸模块（如 npm 包）constlodashUrl=awaitimport.meta.resolve('lodash');console.log(lodashUrl);// file:///user/project/node_modules/lodash-es/lodash.mjs// 自定义基准路径constcustomUrl=awaitimport.meta.resolve('helper.mjs','file:///user/project/lib/');

2.import.meta.dirname&import.meta.filename（v20.11.0+ 稳定）

Node.js 提供的语法糖，直接替代手动转换的__dirname/__filename，无需引入url/path模块。

示例：

// /user/project/app.mjsconsole.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.mjsif(import.meta.main){console.log('我是入口模块');// 执行入口逻辑}else{console.log('我是被导入的模块');}// 运行 node app.mjs → 输出「我是入口模块」// 其他模块 import './app.mjs' → 输出「我是被导入的模块」

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

4.import.meta.resolveSync（同步版本，v18.19.0+/v20.0.0+ 稳定）

import.meta.resolve的同步版本，适用于无需异步的场景：

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

5. 实验性属性（谨慎使用）

• import.meta.url.slice(7)：手动截取file://前缀（不推荐，建议用fileURLToPath）；
• import.meta.env：非 Node.js 原生属性，通常由构建工具（Vite、Webpack）注入环境变量，Node.js 原生不支持。

四、核心使用场景

1. 替代 CommonJS 的__dirname/__filename

ESM 中移除了__dirname/__filename，需通过import.meta实现相同功能：

// 兼容低版本 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. 动态加载模块

结合import()动态导入，基于import.meta.url解析相对路径：

// 动态加载当前目录下的模块asyncfunctionloadModule(moduleName){constmoduleUrl=newURL(`./${moduleName}.mjs`,import.meta.url).href;constmodule=awaitimport(moduleUrl);returnmodule;}loadModule('utils').then(utils=>utils.doSomething());

3. 读取模块所在目录的文件

结合fs/promises读取本地文件，基于import.meta.dirname拼接路径：

import{readFile}from'node:fs/promises';asyncfunctionreadConfig(){// v20.11.0+constconfigPath=`${import.meta.dirname}/config.json`;// 低版本替代：join(__dirname, 'config.json')constcontent=awaitreadFile(configPath,'utf8');returnJSON.parse(content);}

4. 多环境模块入口判断

通过import.meta.main实现模块的「复用+入口」双模式：

// utils.mjsexportfunctionadd(a,b){returna+b;}// 仅作为入口时执行测试if(import.meta.main){console.log('测试 add 方法：',add(1,2));// 3}

5. 解析第三方模块的真实路径

通过import.meta.resolve查看 npm 包的实际安装路径：

asyncfunctiongetPackagePath(pkgName){consturl=awaitimport.meta.resolve(pkgName);// 转为本地路径constpath=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 系统中，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仍可正常访问：

// 合法constresolved=awaitimport.meta.resolve('./a.mjs');console.log(import.meta.url);

4.import.meta.main与子进程/工作线程

• 子进程（child_process）中执行的模块，import.meta.main为true（子进程独立入口）；
• 工作线程（worker_threads）中，import.meta.main取决于线程入口是否为该模块。

5. 兼容性问题

六、与 CommonJS 等效对比

七、总结

import.meta是 ESM 模块的核心元数据工具，Node.js 基于标准扩展了实用属性，核心价值在于：

1. 替代 CommonJS 的__dirname/__filename/require.resolve等特性；
2. 提供模块上下文信息（入口判断、路径解析）；
3. 适配 ESM 的模块化规范，支持动态路径解析。

使用建议：

• 优先使用稳定属性（如url、main、dirname），避免实验性 API；
• 低版本 Node.js 需通过fileURLToPath手动转换路径；
• 结合import()动态导入时，用new URL(relativePath, import.meta.url)解析路径，避免相对路径陷阱。