Vitest exclude 配置详解精确控制测试文件收集范围【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestexclude是 Vitest 中用于从测试文件收集结果中剔除指定文件的核心配置项。本指南基于官方配置文档并结合本仓库源码packages/vitest/src/defaults.ts、packages/vitest/src/node/config/resolveConfig.ts完整讲解exclude的类型定义、默认行为、glob 匹配规则、CLI 叠加特性、与coverage.exclude的区别以及如何安全地扩展默认排除规则帮助你在实际项目中精准控制哪些文件参与测试执行。配置参数速览项目说明类型string[]默认值[**/node_modules/**, **/.git/**]CLI 参数vitest --exclude **/excluded-file --exclude */other-files/*.js解析基准相对于root默认取process.cwd()glob 引擎tinyglobbyexclude接收一组 glob 模式 列表用于从测试文件收集中剔除命中的文件。这些模式会相对于root目录默认是process.cwd()即启动 Vitest 时的工作目录进行解析。默认排除规则及其源码依据默认情况下Vitest 只排除两类路径node_modules目录和.git目录。这一默认值在仓库的 packages/vitest/src/defaults.ts 中定义export const defaultExclude: string[] [ **/node_modules/**, **/.git/**, ]同时configDefaults位于 defaults.ts中exclude: defaultExclude直接引用了这一常量保证类型定义中的default [**/node_modules/**, **/.git/**]见 packages/vitest/src/node/types/config.ts与实际运行时行为完全一致。值得注意的是typecheck选项的exclude默认值同样复用了defaultExclude见 defaults.ts因此类型检查场景下默认排除的目录与测试收集一致。关于 node_modules 的说明虽然node_modules已在默认排除列表中但 Vitest 对依赖的处理与exclude是两套独立机制exclude控制的是测试文件收集范围而依赖是否被转换/外部化由deps相关配置参见 docs/config/deps.md负责。exclude中的node_modules模式主要是防止极少数意外落入测试收集的第三方文件被执行。glob 模式如何被解析Vitest 使用tinyglobby包来解析这些 glob 模式。这一实现事实在源码中有多处印证packages/vitest/src/node/config/resolveConfig.ts 中import { isDynamicPattern } from tinyglobbypackages/vitest/src/node/projects/resolveProjects.ts 中同时引入glob与isDynamicPattern用于项目文件收集packages/vitest/src/node/projects/globProjectFiles.ts 同样使用tinyglobby的glob函数。tinyglobby是fast-glob的现代化替代实现支持**任意层级目录、*单层通配、?单字符、{a,b}花括号扩展、[abc]字符集以及!取反等常见 glob 语法。在编写exclude模式时注意**/node_modules/**匹配任意层级的node_modules目录下的所有内容**/dist/**匹配任意位置的dist构建产物目录./temp/**匹配相对于root的temp目录./前缀在相对于 root 解析后等价于无前缀写法。在配置文件中使用 exclude在vitest.config.ts或vite.config.ts中通过test.exclude配置import { defineConfig } from vitest/config export default defineConfig({ test: { exclude: [ **/node_modules/**, **/dist/**, ./temp/**, ], }, })手动设置会覆盖默认值需要特别强调的是手动在配置中设置exclude会整体替换默认值而不是追加到默认值之后。上例中node_modules仍然被显式写出正是因为如果不写node_modules将不再被排除。推荐做法基于 configDefaults 扩展如果只想在默认排除规则之上追加新模式官方推荐从vitest/config导入configDefaults并展开默认值import { configDefaults, defineConfig } from vitest/config export default defineConfig({ test: { exclude: [ ...configDefaults.exclude, packages/template/*, ./temp/**, ], }, })configDefaults即 defaults.ts 中Object.freeze冻结的只读对象其中exclude的值为[**/node_modules/**, **/.git/**]。展开后最终生效的排除列表既保留默认的两个模式又新增了模板包与临时目录的排除规则。由于该对象被Object.freeze冻结不能直接修改其属性必须通过数组展开spread的方式复制后追加。通过 CLI 传递 exclude叠加式行为exclude也可以通过命令行参数传递且可重复使用vitest --exclude **/excluded-file --exclude */other-files/*.js唯一不覆盖配置的 CLI 选项exclude是 Vitest 中唯一一个通过 CLI 传入时不会覆盖配置文件对应值的选项。其他配置项在 CLI 中给出时通常会覆盖配置而--exclude传入的所有 glob 模式会被追加到配置的exclude列表之后。这一叠加行为在源码中有明确实现。在 packages/vitest/src/node/cli/cac.ts 中CLI 解析器先将--exclude收集到cliExcludeif (argv.exclude) { argv.cliExclude toArray(argv.exclude) delete argv.exclude }随后在配置解析阶段 packages/vitest/src/node/config/resolveConfig.ts 将其合并进最终的exclude数组if (resolved.cliExclude) { resolved.exclude.push(...resolved.cliExclude) }注意这里使用的是push(...)即纯追加而非覆盖。因此 CLI 与配置文件中的排除规则总是同时生效——这也是为什么在仓库的 CLI 参数定义packages/vitest/src/node/cli/cli-config.ts中将该参数描述为 Additional file globs to be excluded from test追加的测试排除 glob。实用场景叠加特性非常适合在不改动配置文件的前提下临时排除文件例如# 临时排除某个 flaky 测试文件 vitest run --exclude **/flaky.test.ts # 排除某目录下的一批文件同时保留 config 中的排除规则 vitest --exclude e2e/** --exclude **/*.snap.test.tsexclude 与 include 的协作关系exclude与include共同决定最终收集的测试文件集合。include定义哪些文件候选参与测试exclude再从候选中剔除不需要的文件。两者都是相对root解析的 glob 模式列表。在实际项目中include默认值[**/*.{test,spec}.?(c|m)[jt]s?(x)]定义于 defaults.ts已经足够宽泛绝大多数不想跑的场景如构建产物目录、临时目录、模板样例、特定命名文件都应当通过扩充exclude而非收紧include来实现这样配置语义更清晰也便于在 watch 模式下快速理解收集范围。exclude 不影响覆盖率统计一个高频误区是在exclude中排除的文件会从覆盖率报告中消失。事实并非如此。exclude只影响测试文件的收集与覆盖率统计完全无关。如果需要从覆盖率报告中移除某些文件必须使用coverage.exclude。这在源码中同样有依据覆盖率配置的默认排除列表是独立的空数组exclude: []见 defaults.ts与测试文件的defaultExclude是两个完全独立的数据来源而覆盖率报告还会在 resolveConfig.ts 中自动追加测试文件、配置文件、**/node_modules/**等模式这说明覆盖率排除有着自己独立的构建逻辑。官方文档对此的警告原文值得牢记该选项不影响覆盖率。如果需要从覆盖率报告中移除某些文件请使用coverage.exclude。实践建议与易错点总结忘记重写默认值手动设置test.exclude会丢弃node_modules/.git的默认排除除非显式包含它们或使用...configDefaults.exclude展开。模式写错基准目录所有 glob 均相对root默认process.cwd()解析不是相对配置文件所在目录。若root被显式配置参见 docs/config/root.md请以root为准。误以为 CLI 覆盖配置--exclude是追加语义源码中resolved.exclude.push(...resolved.cliExclude)不会清空配置文件中的排除列表。混淆 coverage 排除覆盖率移除文件请使用coverage.excludedocs/config/coverage.md而非测试收集的exclude。排除类型检查文件类型测试typecheck的排除默认值同样来自defaultExcludedefaults.ts如需单独控制可在test.typecheck.exclude中配置参见 docs/config/typecheck.md。通过合理组合配置文件中的exclude、configDefaults.exclude展开以及 CLI 的叠加--exclude你可以在不牺牲默认保护的前提下精确、可维护地控制 Vitest 的测试文件收集范围。【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考