Vite import.meta.glob 如何限制构建时收集的文件

在 Vite 项目里，import.meta.glob 很适合做页面目录、文章目录或 SVG 资源索引，但它收集的是构建时能确定的模块集合，不是浏览器运行时的目录查询。模式写得过宽，测试文件和草稿就可能一起进入结果；模式写得过窄，又会出现“为什么某个文件没有被收集”。

官方地址：https://vite.dev/guide/features.html

限制收集范围的关键是把目录、层级、扩展名和排除项写进 glob 字面量；需要进一步控制时，再使用 eager、import、query、base 等选项。不要把变量拼进 glob 参数，Vite 不会按运行时值重新扫描文件。

先用路径模式把收集集合缩到最小

假设入口文件在 src/catalog/loader.ts，目录中只有 src/catalog/pages/*.ts 才是正式页面。最小写法如下：

// 只收集 pages 目录的 TypeScript 模块；参数必须是字面量
const pageLoaders = import.meta.glob('./pages/*.ts')

// 需要遍历时，键是匹配到的路径，值是懒加载函数
for (const [path, load] of Object.entries(pageLoaders)) {
  console.log(path)
  await load()
}

./pages/*.ts 只匹配这一层。如果页面还分在 pages/admin/，要改成 ./pages/**/*.ts。若只收集 Markdown，则直接把扩展名换成 ./pages/**/*.md，不要先收集全部文件再在运行时过滤。

用负模式排除测试文件和草稿

当正式页面和测试文件共用目录时，数组模式比事后筛选更清楚：

// 先收集所有页面，再排除测试和草稿文件
const pages = import.meta.glob([
  './pages/**/*.ts',
  '!./pages/**/*.test.ts',
  '!./pages/**/_*.ts',
])

// pages 的键只代表经过模式筛选后的模块路径
const pagePaths = Object.keys(pages).sort()
console.log(pagePaths)

排除模式以 ! 开头，路径同样要按导入文件的位置书写。这个方案的边界是“静态匹配规则”：如果排除条件来自用户输入，就不能把用户输入直接拼到 import.meta.glob 中，而应在已生成的键集合上做普通数组过滤。

再按加载时机和导出形态收窄结果

默认值是懒加载函数，适合按路由或用户操作再加载。若模块副作用必须在入口初始化阶段发生，可使用 eager: true；如果只需要每个模块的某个导出，则组合 import：

// 只取 setup 导出，并在构建后的入口中直接引用它们
const setups = import.meta.glob('./pages/**/*.ts', {
  import: 'setup',
  eager: true,
})

// setup 仍由键映射保存；这里按需调用已直接导入的函数
for (const [path, setup] of Object.entries(setups)) {
  setup({ path })
}

不要只看到“收集范围”就忽略加载语义：默认模式会形成动态导入和拆分 chunk，eager 则可能增加入口代码体积。对 SVG、JSON 等资源，还可以用 query: '?raw' 或 query: '?url' 配合 import: 'default'，明确拿到文本还是 URL。

构建前后检查四个容易误判的边界

排查“文件没有进入结果”时，先把模式临时收窄到一个明确文件，再逐步放宽层级和扩展名；排查“构建包变大”时，优先检查是否用了 **、是否漏写负模式，以及是否把本来可以懒加载的集合改成了 eager。最后查看构建输出中的模块路径，与 Object.keys 的预期集合逐项对照。

常见问题

能不能把目录名放在变量里动态传给 import.meta.glob？

不能。Vite 要求 glob 的参数是字面量；动态需求应把候选集合预先写成多个静态 glob，再在返回对象的键上筛选。

为什么写了 *.ts 却匹配不到子目录文件？

单个星号通常只覆盖当前层级。需要递归子目录时使用 **/*.ts，并确认相对路径是相对于导入文件而不是项目运行目录。

eager: true 会让收集范围变大吗？

它不改变匹配到哪些文件，但改变加载方式：从默认的懒加载函数变为构建时直接导入，可能增大入口代码或减少拆分，应结合页面访问频率选择。