import.meta.url 是 ES 模块中获取当前模块绝对 URL 的标准方式,返回 file://(Node.js)或 https://(浏览器)开头的完整字符串,需配合 URL API 构建路径,不可直接用于 fs 操作,且注意环境差异与构建工具影响。

import.meta.url 是 ES 模块中获取当前模块绝对 URL 的标准方式,它返回一个以 file://(Node.js)或 https://(浏览器)开头的完整字符串,可用于定位资源、读取同目录文件、构建相对路径等。它不依赖打包工具,原生支持,但需注意运行环境和使用细节。
理解 import.meta.url 的返回值
该属性返回的是当前模块的完整 URL 字符串,不是文件系统路径。在 Node.js 中通常是 file:///absolute/path/to/module.js;在浏览器中则是页面加载该模块时的实际地址,如 https://example.com/js/utils.js。不能直接当 fs 路径用,需转换。
- Node.js 中可用
new URL('./data.json', import.meta.url)构建同目录下的资源 URL - 浏览器中可配合
fetch()加载同目录 JSON、文本等资源 - 不能直接传给
fs.readFileSync(),必须先用fileURLToPath或path.dirname转换
Node.js 中获取当前模块所在目录(__dirname 等效)
ESM 不支持 __dirname,但可通过 import.meta.url + URL API 模拟:
const __dirname = fileURLToPath(import.meta.url).replace(/[^/]+$/, '')- 更推荐:用
const dirname = path.dirname(fileURLToPath(import.meta.url)) - 若只需读取同目录文件,优先用
fs.promises.readFile(new URL('./config.json', import.meta.url)),避免手动拼路径
浏览器中动态加载同目录资源
利用 import.meta.url 构造相对 URL,确保资源路径不随 HTML 入口变化而失效:
-
fetch(new URL('./data.csv', import.meta.url))可靠加载模块同级 CSV 文件 - 搭配
import.meta.resolve()(实验性,尚未广泛支持)可解析包内路径,但目前兼容性差,不建议生产使用 - 注意:Service Worker 或离线缓存场景下,
import.meta.url仍指向原始部署路径,无需额外处理
常见误区与注意事项
容易踩坑的地方往往不在写法,而在环境判断和路径逻辑:
- 不要对
import.meta.url做字符串截断(如.split('file://')[1]),不同平台格式不同(Windows 有盘符,URL 编码可能含 %) - Vite / Webpack 等构建工具会重写
import.meta.url,开发时行为一致,但 SSR 或预渲染需确认服务端是否支持 ESM - TypeScript 中需确保
compilerOptions.module设为nodenext或es2022以上,否则可能报错

















