import.meta详解

import.meta 详解

import.meta 是 JavaScript 模块系统中的一个特殊对象，它提供了关于当前模块的元数据信息。这个特性是在 ES2020（ECMAScript 2020）规范中正式引入的。

基本概念

• import.meta 是一个对象，只能在 ES 模块中使用（不能在 CommonJS 模块或普通脚本中使用）
• 它提供了模块相关的上下文信息
• 最常见的属性是 import.meta.url，但不同环境可能会扩展其他属性

常见属性

import.meta.url

这是最基础也是最常用的属性，返回当前模块的 URL：

console.log(import.meta.url);
// 例如: "file:///C:/projects/my-app/src/main.js" (在浏览器或 Node.js 中)

这个 URL 在不同环境中格式会有所不同：

• 浏览器：通常是完整的 HTTP/HTTPS URL
• Node.js：通常是 file:// 协议的本地文件路径
• Deno：同样是完整的 URL

其他常见扩展属性

不同的运行时环境和构建工具会向 import.meta 添加各自特有的属性：

Vite 中的扩展

Vite 构建工具添加了几个有用的属性：

// 开发环境特有的标志
console.log(import.meta.hot); // HMR API
console.log(import.meta.env); // 环境变量

// 用于资源引用的辅助函数
const imageUrl = new URL('./img.png', import.meta.url).href;

Node.js 中的扩展

// Node.js v20+ 提供
console.log(import.meta.resolve); // 解析模块说明符的函数

Deno 中的扩展

console.log(import.meta.main); // 是否是主模块
console.log(import.meta.permissions); // 权限API

实用案例

1. 获取模块的相对路径

// 获取当前模块的目录路径
const currentModulePath = new URL('.', import.meta.url).pathname;
console.log(currentModulePath);

// 在浏览器中引用相对资源
const imageUrl = new URL('./images/logo.png', import.meta.url).href;
document.querySelector('img').src = imageUrl;

2. 在 Node.js 中读取相对文件

import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

// 获取当前文件的目录路径
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);

// 读取相对于当前模块的文件
const data = readFileSync(join(__dirname, 'data.json'), 'utf8');
console.log(JSON.parse(data));

3. 在 Vite/Webpack 等构建工具中使用环境变量

// Vite 扩展了 import.meta.env
if (import.meta.env.DEV) {
  console.log('开发环境下运行');
} else if (import.meta.env.PROD) {
  console.log('生产环境下运行');
}

// 使用自定义环境变量
const apiUrl = import.meta.env.VITE_API_URL || '/api';

注意事项

1. 仅限 ES 模块：import.meta 只能在使用 import/export 语法的 ES 模块中使用

2. 环境差异：不同环境中 import.meta 可用的属性有差异，使用前最好检查

3. 转译兼容性：如果使用 Babel 等工具转译代码，需要确保它们正确处理 import.meta

4. 替代方案：在不支持 ES 模块的环境中，可以考虑使用：

   • CommonJS 中的 __dirname 和 __filename
   • 打包工具的特殊变量如 process.env

浏览器兼容性

现代浏览器普遍支持 import.meta：

• Chrome 64+
• Firefox 62+
• Safari 11.1+
• Edge 79+

在老旧浏览器中使用时需要通过构建工具处理或提供兼容方案。

import.meta 作为 JavaScript 模块系统的重要组成部分，为开发者提供了获取当前模块上下文信息的标准化方式，在现代前端开发中有着广泛的应用。