Vite import.meta.glob 怎样批量加载模块

在 Vite 项目里，如果一批模块都遵循同一目录和命名规则，逐个写静态 import 很快就会变成维护负担。import.meta.glob 的作用是让 Vite 根据文件模式生成一个模块映射：默认情况下，映射的值是动态导入函数，调用后才加载对应文件。

官方地址：https://vite.dev/

import.meta.glob 返回的到底是什么

先看最小写法。Vite 会在构建阶段识别这个特殊调用，并把匹配到的文件变成一个对象。对象的键是相对路径，值默认是一个动态导入函数，因此可以按路径遍历并按需加载：

const modules = import.meta.glob('./modules/*.js')

for (const [path, load] of Object.entries(modules)) {
  // 默认值是加载器，调用后才得到对应模块的 Promise。
  load().then((module) => {
    // 用路径保留模块来源，方便建立菜单或注册表。
    console.log(path, module)
  })
}

可以把它理解成一张“路径—加载器”表：文件模式决定有哪些键，调用加载器才进入具体模块。默认懒加载还会让匹配模块在生产构建中拆分到独立 chunk，适合内容按需出现的场景。

用字面量模式批量加载 JavaScript 模块

最常见的任务是扫描一个目录，批量加载页面、路由或插件模块。模式要直接写在调用里，不能先放进变量再传入：

const pageModules = import.meta.glob('./pages/*.js')

async function loadPage(path) {
  // 只有调用对应加载器时，目标模块才会被导入。
  const load = pageModules[path]
  if (!load) {
    throw new Error(`未知页面模块：${path}`)
  }
  // 返回模块命名空间，调用方再读取 default 或命名导出。
  return load()
}

这里的 path 只能来自这张映射表的键。如果需要同时匹配多个目录，可以把第一个参数写成字符串数组；如果要排除测试文件，则在数组中加入以 ! 开头的负模式：

const featureModules = import.meta.glob([
  './features/*.js',
  './shared/*.js',
  '!**/*.test.js', // 排除测试模块，避免它们进入这张业务映射表。
])

用选项控制加载时机和导出内容

如果模块必须在初始化阶段就被直接引入，可以使用 eager: true。如果每个文件只需要默认导出，再加上 import: 'default'，返回值就更接近“路径到模块值”的表：

const handlers = import.meta.glob('./handlers/*.js', {
  eager: true,
  import: 'default', // 只取每个模块的 default 导出。
})

for (const [path, handler] of Object.entries(handlers)) {
  // eager 模式下这里拿到的是模块值，而不是待调用的加载器。
  console.log(`注册处理器：${path}`)
  registerHandler(path, handler)
}

只需要命名导出时，可以把 import 改成导出名，例如 'setup'。要注意，eager 改变的是加载时机，不会自动把所有导出变成默认导出；导出选择仍由 import 决定。

用 query 批量读取资源内容或 URL

import.meta.glob 不只适合 JavaScript。处理 SVG、Markdown 等资源时，可以用 query 指定加载形态，再用 import: 'default' 取资源默认值：

const markdownFiles = import.meta.glob('./docs/*.md', {
  query: '?raw',
  import: 'default', // 把每个文件的原始文本作为模块值。
})

const iconUrls = import.meta.glob('./icons/*.svg', {
  query: '?url',
  import: 'default', // 把每个 SVG 的构建后 URL 作为模块值。
})

这两张映射表仍然遵循同一套模式规则：默认不代表立刻读取，是否懒加载还要看有没有设置 eager。如果依赖的插件需要自定义查询参数，也可以把 query 写成对象，但参数必须保持静态。

四个容易踩到的边界

• 参数必须是字面量：import.meta.glob(pattern) 不能用变量表达模式；需要动态选择时，应先准备多张静态映射，再按键选择。
• 路径要符合导入规则：相对模式以 ./ 开头，绝对模式相对项目根目录，别名模式则依赖 Vite 的别名配置。
• 懒加载和 eager 不是同一种返回形态：前者通常要调用函数并等待 Promise，后者直接得到模块或指定导出。
• 它是 Vite 扩展：import.meta.glob 不是浏览器或 ECMAScript 标准 API，换到不支持该转换的构建工具时不能直接照搬。

因此，批量加载模块时可以按这个顺序做选择：先写静态 glob 模式得到范围，再判断模块是否需要按需加载；只有需要启动期副作用或同步注册时才启用 eager，最后用 import 和 query 收窄返回内容。

常见问题

import.meta.glob 为什么不能接变量？

因为 Vite 需要在构建阶段静态识别模式并生成导入关系。把模式藏进运行时变量后，构建器无法确定要收集哪些文件。

默认 glob 和 eager glob 怎么选？

内容只在用户访问或功能触发时需要，就保留默认懒加载；模块必须在初始化阶段直接注册或依赖副作用时，再使用 eager: true。

怎样只拿模块的一个导出？

在选项中设置 import: 'default' 或具体命名导出名。若同时使用 eager，返回表中的值就是选定导出，而不是加载器函数。