Vitest `strictTags` 配置详解：如何让未声明的测试标签在运行前被拦截

ViteststrictTags配置详解：如何让未声明的测试标签在运行前被拦截

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest

strictTags是 Vitest 4.1.0 引入的测试标签（tags）严格校验开关，用于在测试使用未在配置中声明的标签时立即抛错，防止因拼写错误导致错误配置被静默应用、或测试被--tags-filter意外跳过。读完本文，你将掌握该配置的类型语义、CLI 用法、源码层面的校验链路，以及它与--tags-filter强制校验之间的边界。

配置项速览

strictTags的完整定义见 docs/config/stricttags.md，核心信息如下：

默认开启意味着：只要测试声明了配置中不存在的标签，Vitest 就会抛出错误，而不是静默忽略——这正是为了避免"因标签名拼写错误而悄悄应用了错误的配置，或由于--tags-filter导致测试被意外跳过"这类难以排查的问题。

为什么默认开启：一次拼写错误引发的连锁问题

标签系统允许你在配置中预先声明标签并为它们绑定测试选项（超时、重试等），详见 tags 配置。strictTags保护的是标签名的一致性。

假设你在vitest.config.js中声明了frontend标签，但测试里手滑写成了fortnend：

::: code-group

test('renders a form', { tags: ['fortnend'] }, () => { // ... })

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { tags: [ { name: 'frontend' }, ], }, })

:::

在strictTags: true（默认）下，运行测试会立即报错：The tag "fortnend" is not defined in the configuration，并列出所有可用标签。这比让测试"带病运行"、等到 CI 上才发现frontend相关的超时/重试选项从未生效要高效得多。

两种配置方式

方式一：配置文件

在test配置块中显式设置：

import { defineConfig } from 'vitest/config' export default defineConfig({ test: { strictTags: true, // 默认值，可省略 tags: [ { name: 'unit' }, { name: 'e2e', timeout: 60_000 }, ], }, })

如果项目里存在大量历史测试、暂未声明全部标签，可以临时关闭校验以平滑迁移：

export default defineConfig({ test: { strictTags: false, }, })

方式二：命令行

CLI 选项在 cli-config.ts 中注册，声明为无参数布尔开关，与配置文件中的设置等价：

vitest --strict-tags # 等价于 strictTags: true vitest --no-strict-tags # 等价于 strictTags: false

注意 CLI 优先级高于配置文件——用--no-strict-tags运行可以临时放行未声明标签，而无需改动任何代码。

源码视角：严格校验发生在哪里

strictTags并非只在配置解析时生效，而是在多个标签进入路径上分别校验。

默认值与序列化

类型定义位于 config.ts，注释明确说明默认值为true。在 serializeConfig.ts 中，配置被序列化传给运行时：

strictTags: config.strictTags ?? true,

即使你在配置里省略该字段，运行时拿到的也是true。

核心校验函数

所有校验最终收敛到 tags.ts 中的validateTags：

export function validateTags(config: SerializedConfig, tags: string[]): void { if (!config.strictTags) { return } const availableTags = new Set(config.tags.map(tag => tag.name)) for (const tag of tags) { if (!availableTags.has(tag)) { throw createNoTagsError(config.tags, tag) } } }

当strictTags为false时直接返回、不做任何校验；为true时逐标签比对config.tags中声明的名字集合，未命中即抛错。错误信息由createNoTagsError生成：若配置中完全没有声明标签，会提示 "The Vitest config doesn't define any tags"；否则会列出所有可用标签及其description，方便开发者立即定位拼写问题。

三个校验入口

从源码结构看，validateTags被三处调用，覆盖了标签注入的全部渠道：

• ast-collect.ts：在静态收集阶段校验测试定义中的标签；
• collect.ts：校验通过@module-tag注释注入的文件级标签；
• suite.ts：校验 suite 声明时携带的标签。

此外，测试用例自身的标签在 suite.ts 中汇总时还会做一次即时校验：if (!tagDefinition && runner.config.strictTags) throw createNoTagsError(...)。也就是说，无论是test()选项、@module-tag文件注释还是describe套件，未声明的标签都会被拦截。

例外规则：--tags-filter不受strictTags约束

一个容易混淆的边界是：strictTags: false只放宽"测试定义侧"的校验，不放松"过滤侧"的校验。原文档明确强调：

Vitest will always throw an error if--tags-filterflag defines a tag not present in the config.

即无论strictTags为何值，只要--tags-filter里出现配置中不存在的标签，就一定会报错。这背后的原因在于：--tags-filter用于指定"只运行这些标签的测试"，如果标签名拼错，结果是所有测试被静默过滤掉、一个都不跑，这比测试定义侧的拼写错误更具破坏性。

源码实现上，过滤表达式的校验走的是另一条链路——tags.ts 的createTagsFilter与 resolveTagPattern：解析表达式中的每个标签（支持&&、||、!逻辑运算与*通配符）时，都会检查其是否存在于config.tags，不存在则直接抛出The tag pattern "..." is not defined in the configuration。

这一行为在 test-tags.test.ts 中有专门的端到端测试验证：配置strictTags: false且仅声明known标签，测试定义使用known，但通过tagsFilter: ['unknown']运行，仍然会得到错误The tag pattern "unknown" is not defined in the configuration。

关闭校验的实际行为

在 test-tags.test.ts 中，端到端测试验证了strictTags: false的行为：测试声明了未定义的标签unknown，配置仅声明known，此时 stderr 为空、测试正常运行，未定义标签仅作为普通元数据保留，不会被解析出任何绑定选项。

同样的放行逻辑也适用于@module-tag文件级标签——见 test-tags.test.ts，关闭严格模式后，文件注释中的invalid、unknown标签会被原样保留在测试树中而不报错。

这意味着关闭严格校验的真实代价是：拼错的标签既不会报错，也不会匹配到任何标签定义绑定的选项（如超时、重试），并且无法被--tags-filter以正确名字选中，属于典型的"静默失效"场景，应谨慎使用。

让校验更早生效：TypeScript 类型增强

配合 tags 配置 中介绍的类型增强技巧，可以把标签拼写检查前移到编译期，与strictTags的运行期检查形成双保险。新建vitest.shims.ts（确保被tsconfig包含）：

import 'vitest' declare module 'vitest' { interface TestTags { tags: | 'frontend' | 'backend' | 'db' | 'flaky' } }

之后在测试里写tags: ['frontend']之外的字符串，TypeScript 会直接报类型错误，从根本上杜绝拼写错误的可能。

小结

• strictTags默认开启，类型boolean，CLI 支持--strict-tags/--no-strict-tags；
• 它控制测试定义侧（test选项、describe套件、@module-tag注释）对未声明标签的校验，三条校验路径统一收敛于 tags.ts 的validateTags；
• 过滤侧（--tags-filter）的校验是强制性的，与strictTags无关，这是为了杜绝"标签拼错导致全部测试被过滤"的灾难性静默；
• 关闭严格模式只放行定义侧，代价是拼错标签会静默失效且无法被过滤选中；
• 生产环境建议保持默认开启，并用 TypeScript 类型增强把错误拦截在编译期。

【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest