什么是import.meta？揭开模块元数据的神秘面纱

假设你写了一个工具库，需要读取同目录下的配置文件，却发现不知道如何让模块定位自己的路径——这正是许多开发者从 CommonJS 迁移到 ES 模块时遇到的典型痛点。import.meta 就像模块的"身份证"，让模块能够轻松获取自身的上下文信息，完美替代了 CommonJS 中的 __dirname 和 __filename。

简单来说，import.meta 是 JavaScript 运行环境自动创建的对象，专门用于暴露当前模块的元数据。它仅在 ES 模块内部可用，在传统脚本中使用会直接报错。例如，通过 import.meta.url 可以获取模块的完整 URL：浏览器中可能是
https://example.com/utils.js，Node.js 中则是 file:///project/utils.js。

截至 2023 年 10 月，import.meta 全球使用率已达到 94.64%，主流浏览器和 Node.js（v12.17.0+）均已支持。无论是构建工具库还是开发应用，它都能帮你轻松解决模块自定位问题。

核心价值：终结了不同环境下路径获取方式碎片化的历史，让 ES 模块拥有了统一的"身份标识"。

import.meta的核心属性：掌握这些就够了

2.1 url：模块的"住址"

import.meta.url 就像模块的家庭住址，在浏览器中显示网络地址（如
https://example.com/utils.js?version=2），在 Node.js 中则是带 file:// 协议的本地路径（如
file:///home/user/project/main.js）。

实用技巧：结合 URL 构造函数处理路径：

javascript

// 获取当前文件名
const filename = new URL(import.meta.url).pathname.split('/').pop();
console.log(filename); // 输出：main.js

2.2 dirname与filename：Node.js专属路径

Node.js 20.11.0+ 新增的"亲兄弟"属性：dirname 返回目录路径，filename 返回完整文件路径：

javascript

console.log(import.meta.dirname);  // 输出：/home/user/app
console.log(import.meta.filename); // 输出：/home/user/app/utils.js

2.3 resolve()：路径解析神器

resolve() 方法能基于当前模块位置计算目标路径的完整 URL，支持相对路径、绝对路径和裸模块名：

javascript

// 解析同目录下的 api.js
const apiUrl = import.meta.resolve('./api.js');
console.log(apiUrl); // 输出：file:///pages/api.js（Node.js环境）

这三个属性构成了完整的"定位系统"：url提供基础坐标，dirname/filename简化路径操作，resolve()实现动态导航。

实战场景：import.meta这样用才高效

3.1 动态路径处理：告别"路径噩梦"

传统相对路径拼接容易出错，import.meta.url 结合 URL 构造函数可将相对路径转为绝对路径：

javascript

// 读取同目录下的配置文件
import { readFileSync } from 'fs';
const configPath = new URL('./config.json', import.meta.url);
const config = JSON.parse(readFileSync(configPath, 'utf8'));

在浏览器中还能通过查询参数传递配置：

html

<script type="module" src="app.mjs?api=debug&version=2"></script>

javascript

// 解析参数
const params = new URL(import.meta.url).searchParams;
const apiMode = params.get('api'); // "debug"

3.2 Vite批量导入：1行代码导入100个组件

Vite 的 import.meta.globEager 可静态扫描匹配文件，适合路由自动化注册：

typescript

// 批量导入 routes 目录下所有 .ts 文件
const routeModules = import.meta.globEager('./routes/**/*.ts'); 
// 合并所有路由配置
const autoLoadRoutes = Object.values(routeModules).flatMap(module => module.default);

异步加载可用 import.meta.glob（路由懒加载场景）：

javascript

const components = import.meta.glob('./components/*.vue');
// 使用时动态加载：components['./components/Button.vue']()

3.3 环境判断：开发/生产环境自动切换

Vite 项目中 import.meta.env 内置环境信息，无需额外配置：

javascript

// 开发环境启用Mock
if (import.meta.env.DEV) {
  window.mockApi = true;
}

// 生产环境启用错误监控
if (import.meta.env.PROD) {
  initErrorTracking();
}

// 获取环境变量（.env文件中定义）
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;

避坑指南：这些"坑"我替你踩过了

4.1 浏览器：必须在模块脚本中使用

仅 <script type="module"> 标签包裹的代码才能使用 import.meta，否则会报错 Cannot use 'import.meta' outside a module。Safari 16.4 以下版本需手动开启支持。

4.2 构建工具：路径解析规则差异

Webpack 和 Vite 的路径解析逻辑不同，TypeScript 项目需在 tsconfig.json 中设置：

json

{
  "compilerOptions": {
    "target": "es2020",
    "module": "es2020"
  }
}

4.3 Node.js：版本兼容性

dirname 和 filename 需 Node.js 20.11.0+，低版本需用：

javascript

const __dirname = path.dirname(fileURLToPath(import.meta.url));

未来趋势：ES2024带来了什么新变化？

5.1 标准化：import.meta.resolve()将成标配

TC39 第4阶段提案将使 import.meta 行为更统一，未来可能支持模块加载时间、依赖图谱等元数据。

5.2 跨环境统一：浏览器与Node.js"握手"

Node.js、Deno、Bun 等运行时正逐步统一 import.meta 实现，未来浏览器和服务器端路径处理将趋于一致。

总结：从"会用"到"用好"的3个建议

6.1 路径处理首选import.meta.url

用 new URL('./assets', import.meta.url) 替代相对路径拼接，避免"../../"陷阱。

6.2 批量导入用glob更优雅

路由自动化场景优先使用 import.meta.glob 系列API，减少手动导入代码。

6.3 兼容性检查不能少

复杂场景用 import-meta-ponyfill 库统一行为，不同工具链优先参考官方文档。

关键行动：用 import.meta.url 重构一个路径相关功能，或用 glob 优化项目导入逻辑，体验模块化开发的新效率！

动手试试，让你的模块代码更规范、更高效！